Struct ScopeLocal 

pub struct ScopeLocal<T> { /* private fields */ }

Wrapper for scope-local values that are shared within a single scope.

ScopeLocal<T> provides ergonomic access to per-run context values like trace IDs, execution budgets, cancellation tokens, or any other data that should be shared across all services within a single agent run.

Unlike manually threading context through every service, ScopeLocal<T> makes context available anywhere within the scope with a simple resolver.get_required::<ScopeLocal<T>>() call.

Thread Safety

The wrapped value is stored in an Arc<T>, making it cheaply clonable and safe to access from multiple threads within the same scope.

Examples

use ferrous_di::{ServiceCollection, ScopeLocal, Resolver};
use std::sync::Arc;

#[derive(Default)]
struct RunContext {
    trace_id: String,
    max_steps: u32,
    budget_remaining: std::sync::atomic::AtomicU32,
}

let mut services = ServiceCollection::new();
 
// Register scope-local context
services.add_scope_local::<RunContext, _>(|_resolver| {
    Arc::new(RunContext {
        trace_id: "trace-12345".to_string(),
        max_steps: 50,
        budget_remaining: std::sync::atomic::AtomicU32::new(1000),
    })
});

// Any service can access the context
services.add_scoped_factory::<String, _>(|resolver| {
    let ctx = resolver.get_required::<ScopeLocal<RunContext>>();
    format!("Processing with trace: {}", ctx.trace_id)
});

let provider = services.build();
let scope1 = provider.create_scope();
let scope2 = provider.create_scope();

// Each scope gets its own context instance
let result1 = scope1.get_required::<String>();
let result2 = scope2.get_required::<String>();
// Different trace IDs in each scope

Implementations

impl<T> ScopeLocal<T>

pub fn new(value: T) -> Self

Creates a new scope-local wrapper around the given value.

pub fn from_arc(value: Arc<T>) -> Self

Creates a new scope-local wrapper from an existing Arc.

pub fn get(&self) -> &T

Gets a reference to the wrapped value.

pub fn arc(&self) -> Arc<T>

Gets a clone of the underlying Arc.

This is cheap since Arc cloning only increments a reference count.

Trait Implementations

impl<T> Clone for ScopeLocal<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for ScopeLocal<T>

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

Formats the value using the given formatter.

impl<T> Deref for ScopeLocal<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.