mod scope_stack#

module scope_stack#

Scope stack storage and propagation helpers.

The runtime tracks the current scope hierarchy through a shared ScopeStack stored in task-local or thread-local state. Advanced callers can use this module to inspect the active scope chain, attach scope-local middleware, or propagate scope context into worker threads.

Types

type ScopeStackHandle#

Shared handle type for the runtime scope stack.

The runtime stores the active ScopeStack behind an Arc and RwLock so bindings can propagate it across execution contexts while still allowing concurrent readers.

Functions

fn create_scope_stack() -> ScopeStackHandle#

Create a new scope stack handle with an implicit root scope.

The returned handle wraps a freshly initialized ScopeStack inside an Arc and RwLock so it can be shared across async tasks or threads.

Returns

A new ScopeStackHandle containing exactly one implicit root scope.

Notes

The root scope is always present and cannot be removed.

fn current_scope_stack() -> ScopeStackHandle#

Return the scope stack visible to the current execution context.

This resolves task-local scope state first and otherwise falls back to the current thread-local scope stack handle.

Returns

The active ScopeStackHandle for the current async task or thread.

Notes

When no explicit thread-local stack has been installed yet, the default per-thread root-only stack is returned.

fn propagate_scope_to_thread() -> Result<ScopeStackHandle>#

Capture the current scope stack handle for use in another thread.

This returns the handle currently visible to the caller so it can be passed into set_thread_scope_stack elsewhere.

Returns

A Result containing the active ScopeStackHandle.

Errors

Returns an error when the current context does not yet own an active scope stack.

Notes

The returned handle is shared; it does not clone the underlying stack.

fn scope_stack_active() -> bool#

Report whether the current context has an explicitly active scope stack.

This checks task-local state first and otherwise falls back to the thread-local explicit flag.

Returns

true when the current async task or thread already owns an active scope stack and false otherwise.

Notes

A synchronized thread-local stack does not count as explicit unless it was installed through set_thread_scope_stack.

fn set_thread_scope_stack(handle: ScopeStackHandle)#

Install an explicit scope stack for the current thread.

This replaces the thread-local scope stack handle and marks the current thread as explicitly scope-aware for later propagation checks.

Parameters

  • handle: Scope stack handle to install for the current thread.

Returns

().

Notes

Use this when propagating an existing scope stack into worker threads.

fn sync_thread_scope_stack(handle: ScopeStackHandle)#

Synchronize the thread-local scope stack without marking it explicit.

This updates the thread-local slot used by native runtime code while preserving whether the thread was explicitly marked as owning a scope stack.

Parameters

  • handle: Scope stack handle to synchronize into thread-local storage.

Returns

().

Notes

Python bindings use this to mirror ContextVar state into Rust without forcing scope_stack_active() to become true for the thread.

fn task_scope_push(handle: ScopeHandle)#

Push a scope handle onto the active stack.

Parameters

  • handle: Scope handle to push onto the current execution context’s stack.

fn task_scope_remove(uuid: &Uuid) -> Result<ScopeHandle>#

Remove a scope handle from the active stack.

Parameters

  • uuid: UUID of the scope expected to be at the top of the active stack.

Returns

A Result containing the removed ScopeHandle.

Errors

Propagates the same errors returned by ScopeStack::remove.

fn task_scope_top() -> ScopeHandle#

Clone the current top-most scope handle from the active stack.

Returns

A cloned ScopeHandle representing the current active scope.

Structs and Unions

struct ScopeStack#

Mutable stack of active scopes plus their scope-local registries.

The stack always contains an implicit root scope. Additional scopes are pushed as the public API opens lifecycle spans and removed when those spans close.

Implementations

impl ScopeStack#

Functions

fn collect_scope_local_registries<'a, T>(&'a self, field: impl Fn(&'a ScopeLocalRegistries) -> &'a SortedRegistry<T>) -> Vec<&'a SortedRegistry<T>>#

Collect one registry field from every active scope that owns it.

Parameters

  • field: Projection function selecting the registry field to collect from each scope-local registry.

Returns

A vector of registry references ordered from root toward the current top-most scope.

fn collect_scope_local_subscribers(&self) -> Vec<EventSubscriberFn>#

Collect all scope-local subscribers visible from the active stack.

Returns

A vector of subscribers collected from each active scope that owns scope-local registries.

fn find(&self, uuid: &Uuid) -> Option<&ScopeHandle>#

Find a scope handle by UUID.

Parameters

  • uuid: UUID of the scope to search for.

Returns

Some(&ScopeHandle) when the scope is active on this stack and None otherwise.

fn local_registries_mut(&mut self, uuid: &Uuid) -> Option<&mut ScopeLocalRegistries>#

Get or create the scope-local registries for an active scope.

Parameters

  • uuid: UUID of an active scope on this stack.

Returns

Some(&mut ScopeLocalRegistries) when the scope is active and None otherwise.

Notes

When the scope is active but has no registries yet, this function creates an empty scope-local registry set first.

fn new() -> Self#

Create a new scope stack containing only the implicit root scope.

Returns

A ScopeStack initialized with a single root scope and no scope-local registries.

fn push(&mut self, handle: ScopeHandle)#

Push a scope handle onto the top of the stack.

Parameters

  • handle: Scope handle to make the new top-most active scope.

fn remove(&mut self, uuid: &Uuid) -> Result<ScopeHandle>#

Remove the current top scope if it matches uuid.

Parameters

  • uuid: UUID of the scope expected to be at the top of the stack.

Returns

A Result containing the removed ScopeHandle.

Errors

Returns FlowError::InvalidArgument when the scope exists but is not the current top of the stack or when the caller attempts to remove the implicit root scope. Returns FlowError::NotFound when the UUID is not present on the stack.

fn root_uuid(&self) -> Uuid#

Return the UUID of the implicit root scope.

Returns

The stable UUID of the root scope stored at the bottom of the stack.

fn scope_registries_get(&self, uuid: &Uuid) -> Option<&ScopeLocalRegistries>#

Return the scope-local registries for uuid without creating them.

Parameters

  • uuid: UUID of the scope whose registries should be borrowed.

Returns

Some(&ScopeLocalRegistries) when registries already exist for that scope and None otherwise.

fn scopes(&self) -> &[ScopeHandle]#

Return the full ordered stack of scope handles.

Returns

A slice of scopes ordered from root to the current top-most scope.

fn top(&self) -> &ScopeHandle#

Return the current top-most scope handle.

Returns

A shared reference to the active scope at the top of the stack.

Notes

This function never returns None because the implicit root scope is always present.

fn top_mut(&mut self) -> &mut ScopeHandle#

Return the current top-most scope handle mutably.

Returns

A mutable reference to the active scope at the top of the stack.

Traits implemented

impl std::fmt::Debug for ScopeStack#
impl Default for ScopeStack#