Struct Sections 

pub struct Sections { /* private fields */ }

The sections a request reads, and how to read each one.

Built once, at startup, and handed to the framework adapter. Each entry is a closure the adapter calls when a request begins — never during it, which is what makes the reads agree.

Implementations

impl Sections

pub fn new() -> Self

An empty list.

Examples found in repository

examples/core_snapshot.rs (line 63)

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 section<T, F>(self, read: F) -> Self

where T: Any + Send + Sync, F: Fn() -> Option<Arc<T>> + Send + Sync + 'static,

Adds one section, read by read.

let sections = Sections::new().section(try_current);

In a service read is || Database::try_current(), or move || handle.current() for a Dynamic<T>.

Registering the same type twice keeps the last reader, so a composed list can override one entry without rebuilding it.

Examples found in repository

examples/core_snapshot.rs (line 64)

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 section_with_generation<T, F, G>(self, read: F, generation: G) -> Self

where T: Any + Send + Sync, F: Fn() -> Option<Arc<T>> + Send + Sync + 'static, G: Fn() -> u64 + Send + Sync + 'static,

Adds one section, with the install counter that says when it moved.

What sections! uses. The counter lets take tell a snapshot that straddled a reload from one that did not; a section registered through section has none, and a list containing one cannot make that check.

pub fn is_consistent(&self) -> bool

Whether every section can say when it last moved.

false when any was registered through section, which takes a reader and nothing else — take then reads once without checking.

pub fn take(&self) -> Snapshot

Reads every section once.

Called by the adapter when a request begins. A section that has not loaded is left out rather than failing the request: the handler that asks for it gets NotInScope::NotLoaded, and a handler that does not ask is unaffected.

Examples found in repository

examples/core_snapshot.rs (line 72)

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 are registered.

pub fn is_empty(&self) -> bool

Whether nothing is registered.

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

The registered type names, in order.

Examples found in repository

examples/core_snapshot.rs (line 67)

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}");
}

Trait Implementations

impl Debug for Sections

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

Formats the value using the given formatter.

impl Default for Sections

fn default() -> Sections

Returns the “default value” for a type.