Struct tor_guardmgr::GuardMgr
source · pub struct GuardMgr<R: Runtime> { /* private fields */ }
Expand description
A “guard manager” that selects and remembers a persistent set of guard nodes.
This is a “handle”; clones of it share state.
Implementations§
source§impl<R: Runtime> GuardMgr<R>
impl<R: Runtime> GuardMgr<R>
sourcepub fn new<S>(
runtime: R,
state_mgr: S,
config: &impl GuardMgrConfig
) -> Result<Self, GuardMgrError>
pub fn new<S>( runtime: R, state_mgr: S, config: &impl GuardMgrConfig ) -> Result<Self, GuardMgrError>
Create a new “empty” guard manager and launch its background tasks.
It won’t be able to hand out any guards until a NetDirProvider
has
been installed.
sourcepub fn install_netdir_provider(
&self,
provider: &Arc<dyn NetDirProvider>
) -> Result<(), GuardMgrError>
pub fn install_netdir_provider( &self, provider: &Arc<dyn NetDirProvider> ) -> Result<(), GuardMgrError>
Install a NetDirProvider
for use by this guard manager.
It will be used to keep the guards up-to-date with changes from the network directory, and to find new guards when no NetDir is provided to select_guard().
TODO: we should eventually return some kind of a task handle from this task, even though it is not strictly speaking periodic.
The guardmgr retains only a Weak
reference to provider
,
install_netdir_provider
downgrades it on entry,
§Panics
Panics if a NetDirProvider
is already installed.
sourcepub fn install_bridge_desc_provider(
&self,
provider: &Arc<dyn BridgeDescProvider>
) -> Result<(), GuardMgrError>
Available on crate feature bridge-client
only.
pub fn install_bridge_desc_provider( &self, provider: &Arc<dyn BridgeDescProvider> ) -> Result<(), GuardMgrError>
bridge-client
only.Configure a new bridge::BridgeDescProvider
for this GuardMgr
.
It will be used to learn about changes in the set of available bridge descriptors; we’ll inform it whenever our desired set of bridge descriptors changes.
TODO: Same todo as in install_netdir_provider
about task handles.
§Panics
Panics if a bridge::BridgeDescProvider
is already installed.
sourcepub fn store_persistent_state(&self) -> Result<(), GuardMgrError>
pub fn store_persistent_state(&self) -> Result<(), GuardMgrError>
Flush our current guard state to the state manager, if there is any unsaved state.
sourcepub fn reload_persistent_state(&self) -> Result<(), GuardMgrError>
pub fn reload_persistent_state(&self) -> Result<(), GuardMgrError>
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<(), GuardMgrError>
pub fn upgrade_to_owned_persistent_state(&self) -> Result<(), GuardMgrError>
Switch from having an unowned persistent state to having an owned one.
Requires that we hold the lock on the state files.
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 safely become our new netdir.
sourcepub fn mark_all_guards_retriable(&self)
pub fn mark_all_guards_retriable(&self)
Mark every guard as potentially retriable, regardless of how recently we failed to connect to it.
sourcepub fn install_test_netdir(&self, netdir: &NetDir)
Available on crate feature testing
only.
pub fn install_test_netdir(&self, netdir: &NetDir)
testing
only.Configure this guardmgr to use a fixed NetDir
instead of a provider.
This function is for testing only, and is exclusive with
install_netdir_provider
.
§Panics
Panics if any NetDirProvider
has already been installed.
sourcepub fn reconfigure(
&self,
config: &impl GuardMgrConfig
) -> Result<RetireCircuits, ReconfigureError>
pub fn reconfigure( &self, config: &impl GuardMgrConfig ) -> Result<RetireCircuits, ReconfigureError>
Replace the configuration in this GuardMgr
with config
.
sourcepub fn set_filter(&self, filter: GuardFilter)
pub fn set_filter(&self, filter: GuardFilter)
Replace the current GuardFilter
used by this GuardMgr
.
sourcepub fn select_guard(
&self,
usage: GuardUsage
) -> Result<(FirstHop, GuardMonitor, GuardUsable), PickGuardError>
pub fn select_guard( &self, usage: GuardUsage ) -> Result<(FirstHop, GuardMonitor, GuardUsable), PickGuardError>
Select a guard for a given GuardUsage
.
On success, we return a FirstHop
object to identify which
guard we have picked, a GuardMonitor
object that the
caller can use to report whether its attempt to use the guard
succeeded or failed, and a GuardUsable
future that the
caller can use to decide whether a circuit built through the
guard is actually safe to use.
That last point is important: It’s okay to build a circuit
through the guard returned by this function, but you can’t
actually use it for traffic unless the GuardUsable
future
yields “true”.
sourcepub fn note_external_failure<T>(
&self,
identity: &T,
external_failure: ExternalActivity
)where
T: HasRelayIds + ?Sized,
pub fn note_external_failure<T>(
&self,
identity: &T,
external_failure: ExternalActivity
)where
T: HasRelayIds + ?Sized,
Record that after we built a circuit with a guard, something described
in external_failure
went wrong with it.
sourcepub fn note_external_success<T>(
&self,
identity: &T,
external_activity: ExternalActivity
)where
T: HasRelayIds + ?Sized,
pub fn note_external_success<T>(
&self,
identity: &T,
external_activity: ExternalActivity
)where
T: HasRelayIds + ?Sized,
Record that after we built a circuit with a guard, some activity
described in external_activity
was successful with it.
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 GuardMgr<R>where
R: Freeze,
impl<R> RefUnwindSafe for GuardMgr<R>where
R: RefUnwindSafe,
impl<R> Send for GuardMgr<R>
impl<R> Sync for GuardMgr<R>
impl<R> Unpin for GuardMgr<R>where
R: Unpin,
impl<R> UnwindSafe for GuardMgr<R>where
R: UnwindSafe,
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> 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.