Skip to main content

Session

Struct Session 

Source
pub struct Session { /* private fields */ }
Expand description

A long-lived conversation substrate with a single active lease.

§Panics

A session serializes lease admission and release behind one control lock, and every operation on a Session or its Lease that consults that lock propagates a poisoned one rather than recovering it, per the crate-level lock-poisoning contract. The lock guards only the active-lease slot, and no foreign code runs while it is held, so nothing a caller passes can poison it.

The session’s separate transcript-transaction lock is the crate’s one deliberate recovery, for the reason that contract records: a mutation is expected to unwind through it, and a successor must still be able to mutate the transcript afterwards.

Implementations§

Source§

impl Session

Source

pub fn new(id: String, seed: Option<Snapshot>) -> Self

Creates a session from an optional owned transcript snapshot.

§The seed/live boundary lives with the caller

seed is the replayed prefix, so this caller already holds both coordinates the boundary can be named in: the prefix length, and the Version the epoch resumes at. Both remain valid as live work appends, and a composition layer that forks or resumes keeps whichever its own persistence is keyed on.

The transcript stores no such marker, because no core path treats a replayed record differently from a live one: projection, the exchange grammar and replay validity are all properties of the whole history. Recording the boundary here would be storing a number core neither produces nor consumes. Session trees, branching and branch replay are composition-layer concerns built on top of these two coordinates.

Source

pub fn id(&self) -> &str

Returns this session’s identity.

Source

pub fn transcript(&self) -> SnapshotReader

Returns read-only atomic transcript snapshot authority.

Source

pub fn state(&self) -> Reader

Returns read-only owned session-state authority.

Source

pub fn input_mailbox(&self) -> InputMailbox

Returns the shared asynchronous input mailbox.

Shared, despite being returned by value. InputMailbox is a handle: this hands back another one onto this Session’s queue, so pushing to it reaches a Run that is already running, and two calls to input_mailbox address the same queue.

The queue belongs to the Session, not to its current Run or lease. Releasing a lease does not drain unclaimed batches: a successor Run on this Session may claim them at their next eligible boundary. Call InputMailbox::drain explicitly before starting that successor when the composition layer wants a Run-local queue instead.

That matters because InputMailbox::new is also public, and a mailbox built that way belongs to nobody. Pushing to it succeeds, returns nothing, and is never claimed — the one way to inject input and observe no error and no effect. If a batch you pushed never arrived, check that it went through session.input_mailbox().

Source

pub fn try_acquire(&self) -> Option<Lease>

Atomically acquires the sole active lease, or returns None while busy.

Acquisition waits for any in-flight transcript transaction to resolve, so a successor can never observe a committed version whose reservations have not yet published.

§Panics

If the session control lock is poisoned, as the session’s panic conditions describe.

Trait Implementations§

Source§

impl Clone for Session

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 Debug for Session

Source§

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

Prints the session identity, which is what a session is addressed by.

Auto Trait Implementations§

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> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

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.