Struct tor_circmgr::CircMgr

source ·
pub struct CircMgr<R: Runtime> { /* private fields */ }
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.

Implementations§

source§

impl<R: Runtime> CircMgr<R>

source

pub fn new<SM, CFG: CircMgrConfig>( config: &CFG, storage: SM, runtime: &R, chanmgr: Arc<ChanMgr<R>>, guardmgr: GuardMgr<R> ) -> Result<Arc<Self>>
where SM: StateMgr + Send + Sync + 'static,

Construct a new circuit manager.

§Usage note

For the manager to work properly, you will need to call CircMgr::launch_background_tasks.

source

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 TaskHandles that can be used to manage the daemon tasks.

source

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.

source

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.

source

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.

source

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.

source

pub fn update_network_parameters(&self, p: &NetParameters)

👎Deprecated: There is no need to call this function if you have used launch_background_tasks

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.

source

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)

source

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.

source

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.

source

pub async fn get_or_launch_dir_specific<T: IntoOwnedChanTarget>( &self, target: T ) -> Result<Arc<ClientCirc>>

Available on crate feature 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.

source

pub fn builder(&self) -> &CircuitBuilder<R>

Available on crate feature experimental-api only.

Return a reference to the associated CircuitBuilder that this CircMgr will use to create its circuits.

source

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.

source

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.

source

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.

source

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.

source

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§

source§

impl<R: Clone + Runtime> Clone for CircMgr<R>

source§

fn clone(&self) -> CircMgr<R>

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<R: Runtime> Drop for CircMgr<R>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

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> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Conv for T

§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert 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>

Convert 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)

Convert &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)

Convert &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
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> DynClone for T
where T: Clone,

source§

fn __clone_box(&self, _: Private) -> *mut ()

§

impl<T> FmtForward for T

§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> Pipe for T
where T: ?Sized,

§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows 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) -> R
where R: 'a,

Mutably borrows 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
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows 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
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows 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
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T> Tap for T

§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .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
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .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
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
§

impl<T> TryConv for T

§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more