Skip to main content

ScopedState

Struct ScopedState 

Source
pub struct ScopedState<T> { /* private fields */ }
Available on crate feature scoped-state only.
Expand description

A memory backend’s state behind a mutex, gated by a ScopeGate so a conditional-02 SetScope can isolate it and roll it back (docs/design/conditional.md §7).

Demonstration quality. It is correct, but it serializes every scoped method behind one gate and clones the whole value per atomic call. A production backend uses its storage engine’s transactions instead.

Replaces Arc<Mutex<Inner>>. Cloning shares the state and the gate.

  • lock is for async backend methods, reads included: it waits while another task’s scope is open, so no caller sees a change an atomic method may still undo. A task in the open scope passes.
  • lock_unscoped is for sync code and seeding helpers; it never waits on the gate.
  • open is how begin_set opens a scope.

With no scope ever opened, as in a deployment that does not opt in to conditional-02, the gate is always free and lock is a plain mutex lock.

Implementations§

Source§

impl<T> ScopedState<T>

Source

pub fn new(value: T) -> Self

value, behind a gate of its own.

Source

pub fn with_gate(value: T, gate: Arc<ScopeGate>) -> Self

value, behind gate, which other states may share.

Source

pub fn gate(&self) -> &Arc<ScopeGate> ⓘ

The gate, to share with another state through with_gate.

Source

pub async fn lock(&self) -> ScopedGuard<'_, T>

Lock the value for an async backend method.

Waits while a scope opened by another task holds the gate; passes at once when the running task is in the open scope (current_set_scope), or no scope is open. A poisoned mutex is taken anyway: the value is plain data.

Source

pub fn lock_unscoped(&self) -> ScopedGuard<'_, T>

Lock the value without waiting on the gate, for sync code and seeding helpers that never run alongside a scoped method.

Source

pub fn deferring(&self) -> bool

Whether the running task is in an open atomic scope on this state’s gate.

Per-object methods skip their cross-object checks (unique names, cycles, single default, quotas) when it is true: the scope’s validate runs them against the final state at commit, so a swap that passes through a conflict still commits (§4.2).

Source§

impl<T: Clone + Send + 'static> ScopedState<T>

Source

pub async fn open<V>( &self, request: SetScopeRequest<'_>, validate: V, ) -> Box<dyn SetScope>
where V: FnOnce(&T, &T) -> Vec<DeferredFailure> + Send + 'static,

Open the SetScope for request, for ConditionalBackend::begin_set.

Waits for the gate and records request.scope as its owner, so calls made in that scope pass lock and every other task waits until the scope ends. If request.scope already holds the gate (a second state sharing it, opened for the same method), it does not wait.

SetMode::Atomic snapshots the value. Rollback, or dropping the scope, restores the snapshot, so the state string and change log held in T are as before (§4.2). Commit first runs validate(&before, &after); any failures it returns restore the snapshot and reject the commit with CommitError::Rejected.

SetMode::Isolated takes no snapshot and never calls validate: each change stands on its own (§6.1), and the dispatcher writes nothing before the handler runs. Ending the scope only releases the gate.

Trait Implementations§

Source§

impl<T> Clone for ScopedState<T>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<T: Debug> Debug for ScopedState<T>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<T: Default> Default for ScopedState<T>

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl<T> !RefUnwindSafe for ScopedState<T>

§

impl<T> !UnwindSafe for ScopedState<T>

§

impl<T> Forget for ScopedState<T>

§

impl<T> Freeze for ScopedState<T>
where Arc<Mutex<T>>: Freeze,

§

impl<T> Move for ScopedState<T>

§

impl<T> Send for ScopedState<T>
where Arc<Mutex<T>>: Send,

§

impl<T> Sync for ScopedState<T>
where Arc<Mutex<T>>: Sync,

§

impl<T> Unpin for ScopedState<T>
where Arc<Mutex<T>>: Unpin,

§

impl<T> UnsafeUnpin for ScopedState<T>
where Arc<Mutex<T>>: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> ErasedDestructor for T
where T: 'static,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more