Struct tor_dirmgr::DirMgr

source ·
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>

source

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.

source

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.

source

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.

source

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.

source

pub fn bootstrap_started(&self) -> bool

Returns true if a bootstrap attempt is in progress, or successfully completed.

source

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.

source

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.

source

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

source

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.

source

pub fn text(&self, doc: &DocId) -> Result<Option<DocumentText>>

Try to load the text of a single document described by doc from storage.

source

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>

source§

fn netdir(&self, timeliness: Timeliness) -> Result<Arc<NetDir>>

Return a network directory that’s live according to the provided timeliness.
source§

fn events(&self) -> BoxStream<'static, DirEvent>

Return a new asynchronous stream that will receive notification whenever the consensus has changed. Read more
source§

fn params(&self) -> Arc<dyn AsRef<NetParameters>>

Return the latest network parameters. Read more
source§

fn timely_netdir(&self) -> Result<Arc<NetDir>, Error>

Return a reasonable netdir for general usage. Read more

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§

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.
§

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.
§

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.
source§

impl<T> UpcastArcNetDirProvider for T
where T: NetDirProvider,

source§

fn upcast_arc<'a>(self: Arc<T>) -> Arc<dyn NetDirProvider + 'a>
where T: 'a,

Return a view of this object as an Arc<dyn NetDirProvider>
§

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