Trait tor_dirmgr::state::DirState

source · 
pub(crate) trait DirState: Send {
    // Required methods
    fn describe(&self) -> String;
    fn missing_docs(&self) -> Vec<DocId>;
    fn is_ready(&self, ready: Readiness) -> bool;
    fn can_advance(&self) -> bool;
    fn add_from_cache(
        &mut self,
        docs: HashMap<DocId, DocumentText>,
        changed: &mut bool
    ) -> Result<()>;
    fn add_from_download(
        &mut self,
        text: &str,
        request: &ClientRequest,
        source: DocSource,
        storage: Option<&Mutex<Box<dyn Store>>>,
        changed: &mut bool
    ) -> Result<()>;
    fn bootstrap_progress(&self) -> DirProgress;
    fn dl_config(&self) -> DownloadSchedule;
    fn advance(self: Box<Self>) -> Box<dyn DirState>;
    fn reset_time(&self) -> Option<SystemTime>;
    fn reset(self: Box<Self>) -> Box<dyn DirState>;

    // Provided method
    fn get_netdir_change(&mut self) -> Option<NetDirChange<'_>> { ... }
}
Expand description

A “state” object used to represent our progress in downloading a directory.

These state objects are not meant to know about the network, or how to fetch documents at all. Instead, they keep track of what information they are missing, and what to do when they get that information.

Every state object has two possible transitions: “resetting”, and “advancing”. Advancing happens when a state has no more work to do, and needs to transform into a different kind of object. Resetting happens when this state needs to go back to an initial state in order to start over – either because of an error or because the information it has downloaded is no longer timely.

Required Methods§

source

fn describe(&self) -> String

Return a human-readable description of this state.

source

fn missing_docs(&self) -> Vec<DocId>

Return a list of the documents we’re missing.

If every document on this list were to be loaded or downloaded, then the state should either become “ready to advance”, or “complete.”

This list should never grow on a given state; only advancing or resetting the state should add new DocIds that weren’t there before.

source

fn is_ready(&self, ready: Readiness) -> bool

Describe whether this state has reached ready status.

source

fn can_advance(&self) -> bool

Return true if this state can advance to another state via its advance method.

source

fn add_from_cache( &mut self, docs: HashMap<DocId, DocumentText>, changed: &mut bool ) -> Result<()>

Add one or more documents from our cache; returns ‘true’ if there was any change in this state.

Set changed to true if any semantic changes in this state were made.

An error return does not necessarily mean that no data was added; partial successes are possible.

source

fn add_from_download( &mut self, text: &str, request: &ClientRequest, source: DocSource, storage: Option<&Mutex<Box<dyn Store>>>, changed: &mut bool ) -> Result<()>

Add information that we have just downloaded to this state.

This method receives a copy of the original request, and should reject any documents that do not pertain to it.

If storage is provided, then we should write any accepted documents into storage so they can be saved in a cache.

Set changed to true if any semantic changes in this state were made.

An error return does not necessarily mean that no data was added; partial successes are possible.

source

fn bootstrap_progress(&self) -> DirProgress

Return a summary of this state as a DirProgress.

source

fn dl_config(&self) -> DownloadSchedule

Return a configuration for attempting downloads.

source

fn advance(self: Box<Self>) -> Box<dyn DirState>

If possible, advance to the next state.

source

fn reset_time(&self) -> Option<SystemTime>

Return a time (if any) when downloaders should stop attempting to advance this state, and should instead reset it and start over.

source

fn reset(self: Box<Self>) -> Box<dyn DirState>

Reset this state and start over.

Provided Methods§

source

fn get_netdir_change(&mut self) -> Option<NetDirChange<'_>>

If the state object wants to make changes to the currently running NetDir, return the proposed changes.

Implementors§