Crate dcontext 

dcontext

Distributed context propagation for Rust.

dcontext provides a scoped, type-safe key-value store that travels with the execution flow - across function calls, async/sync boundaries, thread spawns, and even process boundaries via serialization.

Architecture

A single thread_local! store is the source of truth. For async code, the WithContext future wrapper swaps the store in/out on each poll, making it effectively task-local without any runtime dependency.

Re-exports

pub use error::ContextError;

Modules

error

value

Macros

register_contexts

Register multiple context types on a builder at once.

Structs

AttachGuard

RAII guard that restores the previous thread-local store on drop.

ContextKey

A typed handle to a registered context entry.

ContextSnapshot

An immutable snapshot of the current context. Clone + Send + Sync.

ContextStore

The active context state. Lives in Cell<Option<ContextStore>>.

RegistrationOptions

Builder for configuring per-key registration options.

RegistryBuilder

Collects context registrations during application startup.

ScopeGuard

RAII guard that reverts a scope on drop.

WithContext

A future wrapped with a ContextStore that is swapped into the thread-local on each poll and swapped back out after.

Traits

ContextFutureExt

Extension trait providing context propagation for futures.

Functions

attach_from_bytes

Deserialize wire-format bytes and attach as root context.

attach_snapshot

Attach a snapshot as root context. Returns an AttachGuard that restores previous state.

attach_snapshot_with_scope

Attach a snapshot and push a named scope in one call.

attach_store

Attach a ContextStore as root context. Returns an AttachGuard.

capture

Capture a snapshot of the current context. Local-only variables (registered with .local_only()) are excluded.

capture_serialized

Capture a snapshot of the current context and serialize it to wire-format bytes.

clear

Clear the context entirely.

fork

Fork the current context. Creates a child store with a frozen parent. Value lookups fall through to the frozen parent (cheap, Arc-shared). Writes are isolated in the child (copy-on-write).

get_context_variable

Get a context variable. Returns None if the key is not set.

initialize

Freeze the registry. Consumes the builder and makes all reads lock-free.

keys_with_metadata

Iterate over all registered keys that have metadata of type M.

make_wire_bytes

Construct wire-format bytes with a single entry.

make_wire_bytes_v

Like make_wire_bytes but allows specifying the wire format version.

max_context_size

Get the current max context size limit. 0 means no limit.

max_scope_chain_len

Get the current max scope chain length. 0 means no limit. Default is 64.

merge_with

Merge values from another store into the current context. Only merges values, not scope chain.

push_scope

Push a named scope onto the context store. Returns a ScopeGuard that pops the scope on drop.

scope_chain

Get the current scope chain — the ordered list of named scopes from root to current.

set_context_variable

Set a context variable.

set_max_context_size

Set the maximum serialized context size in bytes. Serialization functions will return ContextTooLarge if exceeded. Set to 0 to disable (default).

set_max_scope_chain_len

Set the maximum number of entries in the scope chain.

try_initialize

Try to freeze the registry. Returns Err if already initialized.

update_context_variable

Update a context variable using a callback (read-modify-write).

with_metadata

Access typed metadata for a registered key via callback.