pub struct DirMgr<R: Runtime> { /* private fields */ }
Expand description
A directory manager to download, fetch, and cache a Tor directory.
A DirMgr can operate in three modes:
- In offline mode, it only reads from the cache, and can only read once.
- In read-only mode, it reads from the cache, but checks whether it can acquire an associated lock file. If it can, then it enters read-write mode. If not, it checks the cache periodically for new information.
- In read-write mode, it knows that no other process will be writing to the cache, and it takes responsibility for fetching data from the network and updating the directory with new directory information.
Implementations§
Source§impl<R: Runtime> DirMgr<R>
impl<R: Runtime> DirMgr<R>
Sourcepub async fn load_once(runtime: R, config: DirMgrConfig) -> Result<Arc<NetDir>>
pub async fn load_once(runtime: R, config: DirMgrConfig) -> Result<Arc<NetDir>>
Try to load the directory from disk, without launching any kind of update process.
This function runs in offline mode: it will give an error if the result is not up-to-date, or not fully downloaded.
In general, you shouldn’t use this function in a long-running program; it’s only suitable for command-line or batch tools.
Sourcepub async fn load_or_bootstrap_once(
config: DirMgrConfig,
runtime: R,
store: DirMgrStore<R>,
circmgr: Arc<CircMgr<R>>,
) -> Result<Arc<NetDir>>
pub async fn load_or_bootstrap_once( config: DirMgrConfig, runtime: R, store: DirMgrStore<R>, circmgr: Arc<CircMgr<R>>, ) -> Result<Arc<NetDir>>
Return a current netdir, either loading it or bootstrapping it as needed.
Like load_once, but will try to bootstrap (or wait for another process to bootstrap) if we don’t have an up-to-date bootstrapped directory.
In general, you shouldn’t use this function in a long-running program; it’s only suitable for command-line or batch tools.
Sourcepub fn create_unbootstrapped(
config: DirMgrConfig,
runtime: R,
store: DirMgrStore<R>,
circmgr: Arc<CircMgr<R>>,
) -> Result<Arc<Self>>
pub fn create_unbootstrapped( config: DirMgrConfig, runtime: R, store: DirMgrStore<R>, circmgr: Arc<CircMgr<R>>, ) -> Result<Arc<Self>>
Create a new DirMgr
in online mode, but don’t bootstrap it yet.
The DirMgr
can be bootstrapped later with bootstrap
.
Sourcepub async fn bootstrap(self: &Arc<Self>) -> Result<()>
pub async fn bootstrap(self: &Arc<Self>) -> Result<()>
Bootstrap a DirMgr
created in online mode that hasn’t been bootstrapped yet.
This function will not return until the directory is bootstrapped enough to build circuits. It will also launch a background task that fetches any missing information, and that replaces the directory when a new one is available.
This function is intended to be used together with create_unbootstrapped
. There is no
need to call this function otherwise.
If bootstrapping has already successfully taken place, returns early with success.
§Errors
Returns an error if bootstrapping fails. If the error is Error::CantAdvanceState
,
it may be possible to successfully bootstrap later on by calling this function again.
§Panics
Panics if the DirMgr
passed to this function was not created in online mode, such as
via load_once
.
Sourcepub fn bootstrap_started(&self) -> bool
pub fn bootstrap_started(&self) -> bool
Returns true
if a bootstrap attempt is in progress, or successfully completed.
Sourcepub async fn bootstrap_from_config(
config: DirMgrConfig,
runtime: R,
store: DirMgrStore<R>,
circmgr: Arc<CircMgr<R>>,
) -> Result<Arc<Self>>
pub async fn bootstrap_from_config( config: DirMgrConfig, runtime: R, store: DirMgrStore<R>, circmgr: Arc<CircMgr<R>>, ) -> Result<Arc<Self>>
Return a new directory manager from a given configuration, bootstrapping from the network as necessary.
Sourcepub fn reconfigure(
&self,
new_config: &DirMgrConfig,
how: Reconfigure,
) -> Result<(), ReconfigureError>
pub fn reconfigure( &self, new_config: &DirMgrConfig, how: Reconfigure, ) -> Result<(), ReconfigureError>
Try to change our configuration to new_config
.
Actual behavior will depend on the value of how
.
Sourcepub fn bootstrap_events(&self) -> DirBootstrapEvents
pub fn bootstrap_events(&self) -> DirBootstrapEvents
Return a stream of DirBootstrapStatus
events to tell us about changes
in the latest directory’s bootstrap status.
Note that this stream can be lossy: the caller will not necessarily observe every event on the stream
Sourcepub fn events(&self) -> impl Stream<Item = DirEvent>
pub fn events(&self) -> impl Stream<Item = DirEvent>
Return a new asynchronous stream that will receive notification whenever the consensus has changed.
Multiple events may be batched up into a single item: each time this stream yields an event, all you can assume is that the event has occurred at least once.
Sourcepub fn text(&self, doc: &DocId) -> Result<Option<DocumentText>>
pub fn text(&self, doc: &DocId) -> Result<Option<DocumentText>>
Try to load the text of a single document described by doc
from
storage.
Sourcepub fn texts<T>(&self, docs: T) -> Result<HashMap<DocId, DocumentText>>where
T: IntoIterator<Item = DocId>,
pub fn texts<T>(&self, docs: T) -> Result<HashMap<DocId, DocumentText>>where
T: IntoIterator<Item = DocId>,
Load the text for a collection of documents.
If many of the documents have the same type, this can be more
efficient than calling text
.
Trait Implementations§
Source§impl<R: Runtime> NetDirProvider for DirMgr<R>
impl<R: Runtime> NetDirProvider for DirMgr<R>
Source§fn netdir(&self, timeliness: Timeliness) -> Result<Arc<NetDir>>
fn netdir(&self, timeliness: Timeliness) -> Result<Arc<NetDir>>
timeliness
.Source§fn events(&self) -> BoxStream<'static, DirEvent>
fn events(&self) -> BoxStream<'static, DirEvent>
Source§fn params(&self) -> Arc<dyn AsRef<NetParameters>>
fn params(&self) -> Arc<dyn AsRef<NetParameters>>
Source§fn timely_netdir(&self) -> Result<Arc<NetDir>, Error>
fn timely_netdir(&self) -> Result<Arc<NetDir>, Error>
Source§fn wait_for_netdir<'life0, 'async_trait>(
&'life0 self,
timeliness: Timeliness,
) -> Pin<Box<dyn Future<Output = Result<Arc<NetDir>, NetdirProviderShutdown>> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: 'async_trait,
fn wait_for_netdir<'life0, 'async_trait>(
&'life0 self,
timeliness: Timeliness,
) -> Pin<Box<dyn Future<Output = Result<Arc<NetDir>, NetdirProviderShutdown>> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: 'async_trait,
provider
, waiting until one exists.Source§fn wait_for_netdir_to_list<'life0, 'life1, 'async_trait>(
&'life0 self,
target: &'life1 RelayIds,
timeliness: Timeliness,
) -> Pin<Box<dyn Future<Output = Result<(), NetdirProviderShutdown>> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
fn wait_for_netdir_to_list<'life0, 'life1, 'async_trait>(
&'life0 self,
target: &'life1 RelayIds,
timeliness: Timeliness,
) -> Pin<Box<dyn Future<Output = Result<(), NetdirProviderShutdown>> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
Auto Trait Implementations§
impl<R> !Freeze for DirMgr<R>
impl<R> !RefUnwindSafe for DirMgr<R>
impl<R> Send for DirMgr<R>
impl<R> Sync for DirMgr<R>
impl<R> Unpin for DirMgr<R>where
R: Unpin,
impl<R> !UnwindSafe for DirMgr<R>
Blanket Implementations§
§impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
§impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
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>
, which can then be
downcast
into Box<dyn 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>
, which 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> DowncastSend for T
impl<T> DowncastSend for T
§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.§impl<T> TryConv for T
impl<T> TryConv for T
Source§impl<T> UpcastArcNetDirProvider for Twhere
T: NetDirProvider,
impl<T> UpcastArcNetDirProvider for Twhere
T: NetDirProvider,
Source§fn upcast_arc<'a>(self: Arc<T>) -> Arc<dyn NetDirProvider + 'a>where
T: 'a,
fn upcast_arc<'a>(self: Arc<T>) -> Arc<dyn NetDirProvider + 'a>where
T: 'a,
Arc<dyn NetDirProvider>