Struct Snapshot 

pub struct Snapshot { /* private fields */ }

What one request may read: one Arc per section, taken together.

Built by Sections::take when the request begins, and read by an adapter’s extractor. Two reads of the same section answer the same Arc, however far apart in the handler they are and whatever lands in between.

Implementations

impl Snapshot

pub fn get<T: Any + Send + Sync>(&self) -> Option<Arc<T>>

The section of type T this request began with.

None when T was not among the sections, or was among them and had not loaded yet. require tells those apart.

pub fn require<T: Any + Send + Sync>(&self) -> Result<Arc<T>, NotInScope>

The section of type T, or why it is not here.

Errors

NotInScope::NotListed when T was never registered — a wiring mistake, fixed where the layer is built. NotInScope::NotLoaded when it was registered and nothing has installed a value yet — a startup-order mistake, fixed by loading before serving. The two have different fixes, which is why they are different variants.

Examples found in repository

examples/core_snapshot.rs (line 74)

fn main() {
    let sections = Sections::new()
        .section(|| Some(state().lock().expect("not poisoned").0.clone()))
        .section(|| Some(state().lock().expect("not poisoned").1.clone()));

    println!("sections: {:?}\n", sections.names());

    // One `take()` is one reading of every section. Everything read
    // *through the snapshot* afterwards is from that instant — a reload
    // in between cannot tear it.
    let snapshot = sections.take();

    let server = snapshot.require::<Server>().expect("in scope");

    reload(2); // ← a deployment lands mid-request

    let features = snapshot.require::<Features>().expect("in scope");

    println!("through one snapshot, across a reload:");
    println!(
        "  server   = port {}, generation {}",
        server.port, server.generation
    );
    println!(
        "  features = cache {}, generation {} (same instant)\n",
        features.cache, features.generation
    );
    assert_eq!(server.generation, features.generation);

    // The next request's snapshot sees the new state — this is
    // per-request pinning, not staleness.
    let next = sections.take();

    println!("the next snapshot:");
    println!(
        "  features = {:?}\n",
        next.require::<Features>().expect("in scope")
    );

    // And the error half: a type nobody declared answers by name.
    let missing = snapshot.require::<String>().unwrap_err();

    println!("asking for an undeclared section:\n  {missing}");
}

pub fn len(&self) -> usize

How many sections this request may read.

pub fn is_empty(&self) -> bool

Whether it carries nothing at all.

pub fn names(&self) -> Vec<&'static str>

The type names registered, whether or not each had loaded.

pub fn merged_with(self, inner: Self) -> Self

This snapshot with inner’s sections laid over it.

What an adapter uses when layers nest and each carries its own list. The inner one wins where both registered a type, because it is the more specific of the two — and nothing is lost, which is the point: a handler under both layers can read either’s sections.

Trait Implementations

impl Clone for Snapshot

fn clone(&self) -> Snapshot

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Snapshot

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

The section names, never their contents.

A configuration section holds credentials, and {:?} on a request is the kind of thing that reaches a log line.

impl Default for Snapshot

fn default() -> Snapshot

Returns the “default value” for a type.