Struct tor_circmgr::CircMgr
source · pub struct CircMgr<R: Runtime> {
pub(crate) mgr: Arc<AbstractCircMgr<CircuitBuilder<R>, R>>,
pub(crate) predictor: Arc<Mutex<PreemptiveCircuitPredictor>>,
}
Expand description
A Circuit Manager (CircMgr) manages a set of circuits, returning them when they’re suitable, and launching them if they don’t already exist.
Right now, its notion of “suitable” is quite rudimentary: it just believes in two kinds of circuits: Exit circuits, and directory circuits. Exit circuits are ones that were created to connect to a set of ports; directory circuits were made to talk to directory caches.
This is a “handle”; clones of it share state.
Fields§
§mgr: Arc<AbstractCircMgr<CircuitBuilder<R>, R>>
The underlying circuit manager object that implements our behavior.
predictor: Arc<Mutex<PreemptiveCircuitPredictor>>
A preemptive circuit predictor, for, uh, building circuits preemptively.
Implementations§
source§impl<R: Runtime> CircMgr<R>
impl<R: Runtime> CircMgr<R>
sourcepub fn new<SM, CFG: CircMgrConfig>(
config: &CFG,
storage: SM,
runtime: &R,
chanmgr: Arc<ChanMgr<R>>,
guardmgr: GuardMgr<R>
) -> Result<Arc<Self>>
pub fn new<SM, CFG: CircMgrConfig>( config: &CFG, storage: SM, runtime: &R, chanmgr: Arc<ChanMgr<R>>, guardmgr: GuardMgr<R> ) -> Result<Arc<Self>>
Construct a new circuit manager.
§Usage note
For the manager to work properly, you will need to call CircMgr::launch_background_tasks
.
sourcepub fn launch_background_tasks<D>(
self: &Arc<Self>,
runtime: &R,
dir_provider: &Arc<D>,
state_mgr: FsStateMgr
) -> Result<Vec<TaskHandle>>where
D: NetDirProvider + 'static + ?Sized,
pub fn launch_background_tasks<D>(
self: &Arc<Self>,
runtime: &R,
dir_provider: &Arc<D>,
state_mgr: FsStateMgr
) -> Result<Vec<TaskHandle>>where
D: NetDirProvider + 'static + ?Sized,
Launch the periodic daemon tasks required by the manager to function properly.
Returns a set of [TaskHandle
]s that can be used to manage the daemon tasks.
sourcepub fn reconfigure<CFG: CircMgrConfig>(
&self,
new_config: &CFG,
how: Reconfigure
) -> Result<(), ReconfigureError>
pub fn reconfigure<CFG: CircMgrConfig>( &self, new_config: &CFG, how: Reconfigure ) -> Result<(), ReconfigureError>
Try to change our configuration settings to new_config
.
The actual behavior here will depend on the value of how
.
sourcepub fn reload_persistent_state(&self) -> Result<()>
pub fn reload_persistent_state(&self) -> Result<()>
Reload state from the state manager.
We only call this method if we don’t have the lock on the state files. If we have the lock, we only want to save.
sourcepub fn upgrade_to_owned_persistent_state(&self) -> Result<()>
pub fn upgrade_to_owned_persistent_state(&self) -> Result<()>
Switch from having an unowned persistent state to having an owned one.
Requires that we hold the lock on the state files.
sourcepub fn store_persistent_state(&self) -> Result<bool>
pub fn store_persistent_state(&self) -> Result<bool>
Flush state to the state manager, if there is any unsaved state and we have the lock.
Return true if we saved something; false if we didn’t have the lock.
sourcepub fn update_network_parameters(&self, p: &NetParameters)
👎Deprecated: There is no need to call this function if you have used launch_background_tasks
pub fn update_network_parameters(&self, p: &NetParameters)
Reconfigure this circuit manager using the latest set of network parameters.
This is deprecated as a public function: launch_background_tasks
now
ensures that this happens as needed.
sourcepub fn netdir_is_sufficient(&self, netdir: &NetDir) -> bool
pub fn netdir_is_sufficient(&self, netdir: &NetDir) -> bool
Return true if netdir
has enough information to be used for this
circuit manager.
(This will check whether the netdir is missing any primary guard microdescriptors)
sourcepub async fn get_or_launch_dir(
&self,
netdir: DirInfo<'_>
) -> Result<Arc<ClientCirc>>
pub async fn get_or_launch_dir( &self, netdir: DirInfo<'_> ) -> Result<Arc<ClientCirc>>
Return a circuit suitable for sending one-hop BEGINDIR streams, launching it if necessary.
sourcepub async fn get_or_launch_exit(
&self,
netdir: DirInfo<'_>,
ports: &[TargetPort],
isolation: StreamIsolation,
country_code: Option<CountryCode>
) -> Result<Arc<ClientCirc>>
pub async fn get_or_launch_exit( &self, netdir: DirInfo<'_>, ports: &[TargetPort], isolation: StreamIsolation, country_code: Option<CountryCode> ) -> Result<Arc<ClientCirc>>
Return a circuit suitable for exiting to all of the provided
ports
, launching it if necessary.
If the list of ports is empty, then the chosen circuit will still end at some exit.
sourcepub async fn get_or_launch_dir_specific<T: IntoOwnedChanTarget>(
&self,
target: T
) -> Result<Arc<ClientCirc>>
Available on crate feature specific-relay
only.
pub async fn get_or_launch_dir_specific<T: IntoOwnedChanTarget>( &self, target: T ) -> Result<Arc<ClientCirc>>
specific-relay
only.Return a circuit to a specific relay, suitable for using for direct (one-hop) directory downloads.
This could be used, for example, to download a descriptor for a bridge.
sourcepub(crate) async fn launch_hs_unmanaged<T>(
&self,
planned_target: Option<T>,
dir: &NetDir,
kind: HsCircStubKind
) -> Result<Arc<ClientCirc>>where
T: IntoOwnedChanTarget,
Available on crate feature hs-common
only.
pub(crate) async fn launch_hs_unmanaged<T>(
&self,
planned_target: Option<T>,
dir: &NetDir,
kind: HsCircStubKind
) -> Result<Arc<ClientCirc>>where
T: IntoOwnedChanTarget,
hs-common
only.Create and return a new (typically anonymous) circuit for use as an
onion service circuit of type kind
.
This circuit is guaranteed not to have been used for any traffic previously, and it will not be given out for any other requests in the future unless explicitly re-registered with a circuit manager.
If planned_target
is provided, then the circuit will be built so that
it does not share any family members with the provided target. (The
circuit will not be extended to that target itself!)
Used to implement onion service clients and services.
sourcepub(crate) async fn launch_circuits_preemptively(
&self,
netdir: DirInfo<'_>
) -> Result<(), PreemptiveCircError>
pub(crate) async fn launch_circuits_preemptively( &self, netdir: DirInfo<'_> ) -> Result<(), PreemptiveCircError>
Launch circuits preemptively, using the preemptive circuit predictor’s predictions.
§Note
This function is invoked periodically from
continually_preemptively_build_circuits()
.
sourcepub fn builder(&self) -> &CircuitBuilder<R>
Available on crate feature experimental-api
only.
pub fn builder(&self) -> &CircuitBuilder<R>
experimental-api
only.Return a reference to the associated CircuitBuilder that this CircMgr will use to create its circuits.
sourcepub fn retire_circ(&self, circ_id: &UniqId)
pub fn retire_circ(&self, circ_id: &UniqId)
If circ_id
is the unique identifier for a circuit that we’re
keeping track of, don’t give it out for any future requests.
sourcepub(crate) fn retire_all_circuits(&self)
pub(crate) fn retire_all_circuits(&self)
Mark every circuit that we have launched so far as unsuitable for any future requests. This won’t close existing circuits that have streams attached to them, but it will prevent any future streams from being attached.
TODO: we may want to expose this eventually. If we do, we should be very clear that you don’t want to use it haphazardly.
sourcepub fn estimate_timeout(&self, timeout_action: &Action) -> Duration
pub fn estimate_timeout(&self, timeout_action: &Action) -> Duration
Return an estimate-based delay for how long a given
Action
should be allowed to complete.
Note that you do not need to use this function in order to get
reasonable timeouts for the circuit-building operations provided by the
tor-circmgr
crate: those, unless specifically noted, always use these
timeouts to cancel circuit operations that have taken too long.
Instead, you should only use this function when you need to estimate how
long some other operation should take to complete. For example, if
you are sending a request over a 3-hop circuit and waiting for a reply,
you might choose to wait for estimate_timeout(Action::RoundTrip { length: 3 })
.
Note also that this function returns a timeout that the operation should be permitted to complete, not an estimated Duration that the operation will take to complete. Timeouts are chosen to ensure that most operations will complete, but very slow ones will not. So even if we expect that a circuit will complete in (say) 3 seconds, we might still allow a timeout of 4.5 seconds, to ensure that most circuits can complete.
Estimate-based timeouts may change over time, given observations on the actual amount of time needed for circuits to complete building. If not enough information has been gathered, a reasonable default will be used.
sourcepub(crate) fn expire_circuits(&self)
pub(crate) fn expire_circuits(&self)
Expire every circuit that has been dirty for too long.
Expired circuits are not closed while they still have users, but they are no longer given out for new requests.
sourcepub(crate) fn launch_timeout_testing_circuit_if_appropriate(
&self,
netdir: &NetDir
) -> Result<()>
pub(crate) fn launch_timeout_testing_circuit_if_appropriate( &self, netdir: &NetDir ) -> Result<()>
If we need to launch a testing circuit to judge our circuit build timeouts timeouts, do so.
§Note
This function is invoked periodically from
continually_launch_timeout_testing_circuits
.
sourcepub(crate) async fn keep_circmgr_params_updated<D>(
events: impl Stream<Item = DirEvent> + Unpin,
circmgr: Weak<Self>,
dirmgr: Weak<D>
)where
D: NetDirProvider + 'static + ?Sized,
pub(crate) async fn keep_circmgr_params_updated<D>(
events: impl Stream<Item = DirEvent> + Unpin,
circmgr: Weak<Self>,
dirmgr: Weak<D>
)where
D: NetDirProvider + 'static + ?Sized,
Whenever a [DirEvent::NewConsensus
] arrives on events
, update
circmgr
with the consensus parameters from dirmgr
.
Exit when events
is closed, or one of circmgr
or dirmgr
becomes
dangling.
This is a daemon task: it runs indefinitely in the background.
sourcepub(crate) async fn continually_launch_timeout_testing_circuits<D>(
sched: TaskSchedule<R>,
circmgr: Weak<Self>,
dirmgr: Weak<D>
)where
D: NetDirProvider + 'static + ?Sized,
pub(crate) async fn continually_launch_timeout_testing_circuits<D>(
sched: TaskSchedule<R>,
circmgr: Weak<Self>,
dirmgr: Weak<D>
)where
D: NetDirProvider + 'static + ?Sized,
Run indefinitely, launching circuits as needed to get a good estimate for our circuit build timeouts.
Exit when we notice that circmgr
or dirmgr
has been dropped.
This is a daemon task: it runs indefinitely in the background.
sourcepub(crate) async fn update_persistent_state(
sched: TaskSchedule<R>,
circmgr: Weak<Self>,
statemgr: FsStateMgr
)
pub(crate) async fn update_persistent_state( sched: TaskSchedule<R>, circmgr: Weak<Self>, statemgr: FsStateMgr )
Run forever, periodically telling circmgr
to update its persistent
state.
Exit when we notice that circmgr
has been dropped.
This is a daemon task: it runs indefinitely in the background.
sourcepub(crate) async fn continually_preemptively_build_circuits<D>(
sched: TaskSchedule<R>,
circmgr: Weak<Self>,
dirmgr: Weak<D>
)where
D: NetDirProvider + 'static + ?Sized,
pub(crate) async fn continually_preemptively_build_circuits<D>(
sched: TaskSchedule<R>,
circmgr: Weak<Self>,
dirmgr: Weak<D>
)where
D: NetDirProvider + 'static + ?Sized,
Run indefinitely, launching circuits where the preemptive circuit predictor thinks it’d be a good idea to have them.
Exit when we notice that circmgr
or dirmgr
has been dropped.
This is a daemon task: it runs indefinitely in the background.
§Note
This would be better handled entirely within tor-circmgr
, like
other daemon tasks.
sourcepub fn note_external_failure(
&self,
target: &impl ChanTarget,
external_failure: ExternalActivity
)
pub fn note_external_failure( &self, target: &impl ChanTarget, external_failure: ExternalActivity )
Record that a failure occurred on a circuit with a given guard, in a way that makes us unwilling to use that guard for future circuits.
sourcepub fn note_external_success(
&self,
target: &impl ChanTarget,
external_activity: ExternalActivity
)
pub fn note_external_success( &self, target: &impl ChanTarget, external_activity: ExternalActivity )
Record that a success occurred on a circuit with a given guard, in a way that makes us possibly willing to use that guard for future circuits.
sourcepub fn skew_events(&self) -> ClockSkewEvents
pub fn skew_events(&self) -> ClockSkewEvents
Return a stream of events about our estimated clock skew; these events
are None
when we don’t have enough information to make an estimate,
and Some(
SkewEstimate
)
otherwise.
Note that this stream can be lossy: if the estimate changes more than one before you read from the stream, you might only get the most recent update.
Trait Implementations§
Auto Trait Implementations§
impl<R> Freeze for CircMgr<R>
impl<R> !RefUnwindSafe for CircMgr<R>
impl<R> Send for CircMgr<R>
impl<R> Sync for CircMgr<R>
impl<R> Unpin for CircMgr<R>
impl<R> !UnwindSafe for CircMgr<R>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Conv for T
impl<T> Conv for T
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
.§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.§impl<T> DowncastSync for T
impl<T> DowncastSync for T
§impl<T> FmtForward for T
impl<T> FmtForward for T
§fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
fn fmt_binary(self) -> FmtBinary<Self>where
Self: Binary,
self
to use its Binary
implementation when Debug
-formatted.§fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
fn fmt_display(self) -> FmtDisplay<Self>where
Self: Display,
self
to use its Display
implementation when
Debug
-formatted.§fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
fn fmt_lower_exp(self) -> FmtLowerExp<Self>where
Self: LowerExp,
self
to use its LowerExp
implementation when
Debug
-formatted.§fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
fn fmt_lower_hex(self) -> FmtLowerHex<Self>where
Self: LowerHex,
self
to use its LowerHex
implementation when
Debug
-formatted.§fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
fn fmt_octal(self) -> FmtOctal<Self>where
Self: Octal,
self
to use its Octal
implementation when Debug
-formatted.§fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
fn fmt_pointer(self) -> FmtPointer<Self>where
Self: Pointer,
self
to use its Pointer
implementation when
Debug
-formatted.§fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
fn fmt_upper_exp(self) -> FmtUpperExp<Self>where
Self: UpperExp,
self
to use its UpperExp
implementation when
Debug
-formatted.§fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
fn fmt_upper_hex(self) -> FmtUpperHex<Self>where
Self: UpperHex,
self
to use its UpperHex
implementation when
Debug
-formatted.§fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
fn fmt_list(self) -> FmtList<Self>where
&'a Self: for<'a> IntoIterator,
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more§impl<T> Pipe for Twhere
T: ?Sized,
impl<T> Pipe for Twhere
T: ?Sized,
§fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> Rwhere
Self: Sized,
§fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> Rwhere
R: 'a,
self
and passes that borrow into the pipe function. Read more§fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
§fn pipe_borrow_mut<'a, B, R>(
&'a mut self,
func: impl FnOnce(&'a mut B) -> R
) -> R
fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
§fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
self
, then passes self.as_ref()
into the pipe function.§fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
self
, then passes self.as_mut()
into the pipe
function.§fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
self
, then passes self.deref()
into the pipe function.§impl<T> Tap for T
impl<T> Tap for T
§fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
Borrow<B>
of a value. Read more§fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
BorrowMut<B>
of a value. Read more§fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
AsRef<R>
view of a value. Read more§fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
AsMut<R>
view of a value. Read more§fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
Deref::Target
of a value. Read more§fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
Deref::Target
of a value. Read more§fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self
.tap()
only in debug builds, and is erased in release builds.§fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self
.tap_mut()
only in debug builds, and is erased in release
builds.§fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
.tap_borrow()
only in debug builds, and is erased in release
builds.§fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
.tap_borrow_mut()
only in debug builds, and is erased in release
builds.§fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
.tap_ref()
only in debug builds, and is erased in release
builds.§fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
.tap_ref_mut()
only in debug builds, and is erased in release
builds.§fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
.tap_deref()
only in debug builds, and is erased in release
builds.