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
impl Session
Sourcepub fn new(id: String, seed: Option<Snapshot>) -> Self
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.
Sourcepub fn transcript(&self) -> SnapshotReader
pub fn transcript(&self) -> SnapshotReader
Returns read-only atomic transcript snapshot authority.
Sourcepub fn input_mailbox(&self) -> InputMailbox
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().
Sourcepub fn try_acquire(&self) -> Option<Lease>
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.