reef_core/runtime/session.rs
1//! Exclusive session leases, synchronous admission, and targeted input.
2//!
3//! Four properties define the module: one active lease at a time, mutation only
4//! through a held lease, an explicit admission barrier, and FIFO targeted input.
5
6use std::collections::VecDeque;
7use std::error::Error;
8use std::fmt;
9use std::sync::{Arc, Mutex, MutexGuard};
10#[cfg(test)]
11use std::sync::{Barrier, TryLockError, mpsc};
12
13use crate::redact::Locked;
14use crate::state::session_state::{self, Writer};
15use crate::transcript::item::Item;
16use crate::transcript::store::{self, Snapshot, SnapshotReader, Store, Version};
17
18/// A lease admission or mutation failure.
19#[derive(Clone, Debug, Eq, PartialEq)]
20#[non_exhaustive]
21pub enum LeaseError {
22 /// This lease has already released its authority.
23 Released,
24 /// Admission was already committed for this lease.
25 AlreadyAdmitted,
26 /// The underlying transcript rejected the mutation.
27 Transcript(store::Error),
28}
29
30impl fmt::Display for LeaseError {
31 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
32 match self {
33 Self::Released => formatter.write_str("session lease released"),
34 Self::AlreadyAdmitted => formatter.write_str("session lease already admitted"),
35 Self::Transcript(error) => error.fmt(formatter),
36 }
37 }
38}
39
40impl Error for LeaseError {
41 fn source(&self) -> Option<&(dyn Error + 'static)> {
42 match self {
43 Self::Transcript(error) => Some(error),
44 Self::Released | Self::AlreadyAdmitted => None,
45 }
46 }
47}
48
49/// The lifecycle phase at which an input batch may be admitted.
50#[derive(Clone, Copy, Debug, Eq, PartialEq)]
51pub enum InputTarget {
52 /// Extend the active turn at its next legal step boundary.
53 NextStep,
54 /// Open a distinct turn after the active turn ends.
55 NextTurn,
56}
57
58/// A requested input batch contained no transcript items.
59#[derive(Clone, Copy, Debug, Eq, PartialEq)]
60pub struct EmptyInputBatchError;
61
62impl fmt::Display for EmptyInputBatchError {
63 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
64 formatter.write_str("input batch must not be empty")
65 }
66}
67
68impl Error for EmptyInputBatchError {}
69
70/// One owned, ordered input batch with an immutable admission target.
71#[derive(Clone, Debug)]
72pub struct InputBatch {
73 target: InputTarget,
74 items: Vec<Item>,
75}
76
77impl InputBatch {
78 /// Freezes an owned non-empty batch for one admission target.
79 ///
80 /// # Errors
81 ///
82 /// [`EmptyInputBatchError`] if `items` is empty. An empty batch would occupy
83 /// a place in the mailbox's FIFO order and then open a Turn or Step boundary
84 /// with nothing to admit, so it is refused at construction rather than
85 /// discarded later, where the discard would be invisible to whoever queued it.
86 pub fn new(target: InputTarget, items: Vec<Item>) -> Result<Self, EmptyInputBatchError> {
87 if items.is_empty() {
88 return Err(EmptyInputBatchError);
89 }
90 Ok(Self { target, items })
91 }
92
93 /// Returns the frozen target.
94 #[must_use]
95 pub const fn target(&self) -> InputTarget {
96 self.target
97 }
98
99 /// Returns the ordered owned payload by immutable view.
100 #[must_use]
101 pub fn items(&self) -> &[Item] {
102 &self.items
103 }
104
105 /// Transfers the frozen target and owned payload together.
106 #[must_use]
107 pub fn into_parts(self) -> (InputTarget, Vec<Item>) {
108 (self.target, self.items)
109 }
110}
111
112/// Thread-safe FIFO input storage with target-selective atomic claims.
113///
114/// # Panics
115///
116/// Every method here propagates a poisoned queue lock rather than recovering it,
117/// per the crate-level [lock-poisoning contract](crate#lock-poisoning). Nothing a
118/// caller passes can cause that: the queue holds owned [`InputBatch`] values and
119/// no foreign code runs under the lock.
120#[derive(Clone, Default)]
121pub struct InputMailbox {
122 batches: Arc<Mutex<VecDeque<InputBatch>>>,
123}
124
125impl fmt::Debug for InputMailbox {
126 /// Reports the queue depth at one non-blocking observation.
127 ///
128 /// The mailbox is the session's only concurrent write entry point, so a
129 /// formatter that waited for the queue lock could stall the very producer
130 /// it is describing. On contention it says so rather than guessing.
131 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
132 let mut mailbox = formatter.debug_struct("InputMailbox");
133 match self.batches.try_lock() {
134 Ok(batches) => mailbox.field("batches", &batches.len()),
135 Err(_contended_or_poisoned) => mailbox.field("batches", &Locked),
136 }
137 .finish()
138 }
139}
140
141impl InputMailbox {
142 /// Creates an empty mailbox attached to no Session.
143 ///
144 /// This is for a composition layer assembling its own queue — a test double,
145 /// or a staging buffer drained into a real inbox later. It is **not** how you
146 /// reach a running Run: [`Session::input_mailbox`] returns a handle onto the
147 /// Session's own queue, and a mailbox built here shares nothing with it, so
148 /// pushing to one succeeds and is never claimed by anybody.
149 #[must_use]
150 pub fn new() -> Self {
151 Self::default()
152 }
153
154 /// Moves one already-frozen owned batch into global FIFO order.
155 ///
156 /// # Panics
157 ///
158 /// If the queue lock is poisoned, as
159 /// [the mailbox's panic conditions](InputMailbox#panics) describe.
160 pub fn push(&self, batch: InputBatch) {
161 self.batches
162 .lock()
163 .expect("injection mailbox lock poisoned")
164 .push_back(batch);
165 }
166
167 /// Atomically removes the oldest batch for `target` without reordering peers.
168 ///
169 /// # Panics
170 ///
171 /// If the queue lock is poisoned, as
172 /// [the mailbox's panic conditions](InputMailbox#panics) describe.
173 #[must_use]
174 pub fn claim(&self, target: InputTarget) -> Option<InputBatch> {
175 let mut batches = self
176 .batches
177 .lock()
178 .expect("injection mailbox lock poisoned");
179 let index = batches.iter().position(|batch| batch.target == target)?;
180 batches.remove(index)
181 }
182
183 /// Atomically removes every currently queued batch in FIFO order.
184 ///
185 /// # Panics
186 ///
187 /// If the queue lock is poisoned, as
188 /// [the mailbox's panic conditions](InputMailbox#panics) describe.
189 #[must_use]
190 pub fn drain(&self) -> Vec<InputBatch> {
191 std::mem::take(
192 &mut *self
193 .batches
194 .lock()
195 .expect("injection mailbox lock poisoned"),
196 )
197 .into()
198 }
199
200 /// Returns the number of queued batches at one lock linearization point.
201 ///
202 /// # Panics
203 ///
204 /// If the queue lock is poisoned, as
205 /// [the mailbox's panic conditions](InputMailbox#panics) describe.
206 #[must_use]
207 pub fn len(&self) -> usize {
208 self.batches
209 .lock()
210 .expect("injection mailbox lock poisoned")
211 .len()
212 }
213
214 /// Reports whether the mailbox is empty at one lock linearization point.
215 ///
216 /// # Panics
217 ///
218 /// If the queue lock is poisoned, as
219 /// [the mailbox's panic conditions](InputMailbox#panics) describe.
220 #[must_use]
221 pub fn is_empty(&self) -> bool {
222 self.len() == 0
223 }
224}
225
226struct LeaseToken {
227 _identity: u8,
228}
229
230struct ActiveLease {
231 token: Arc<LeaseToken>,
232 admitted: bool,
233}
234
235struct Control {
236 active: Option<ActiveLease>,
237}
238
239struct SessionInner {
240 id: String,
241 transcript: Store,
242 state: session_state::Store,
243 input_mailbox: InputMailbox,
244 /// The session's sole transcript-transaction authority.
245 ///
246 /// A live transcript mutation is a reserve-commit-publish transaction that
247 /// spans more than the store's own lock, so the session owns one outer lock
248 /// that every mutation path shares: the reservation controller, a direct
249 /// compare-and-set through [`Lease`], lease release, and successor
250 /// acquisition. Holding it session-wide rather than per controller instance
251 /// is what makes "no second mutation crosses an unresolved transaction"
252 /// true for callers the controller does not know about.
253 ///
254 /// Lock order is always this lock before [`SessionInner::control`], and no
255 /// path ever takes them in the other order.
256 transaction: Mutex<()>,
257 control: Mutex<Control>,
258 #[cfg(test)]
259 admit_before_control: Mutex<Option<Arc<TestOverlap>>>,
260 #[cfg(test)]
261 admit_with_control: Mutex<Option<Arc<TestOverlap>>>,
262 #[cfg(test)]
263 commit_overlap: Mutex<Option<Arc<TestOverlap>>>,
264 #[cfg(test)]
265 release_probe: Mutex<Option<Arc<TestOverlap>>>,
266 #[cfg(test)]
267 transaction_arrivals: Mutex<Option<mpsc::Sender<()>>>,
268}
269
270impl SessionInner {
271 /// Acquires the session's sole transcript-transaction authority.
272 ///
273 /// Every transcript mutation path funnels through here, so this is the one
274 /// place the session-wide transaction domain is entered. The lock is not
275 /// reentrant: a caller that already holds a transaction must reuse it rather
276 /// than open a second one.
277 ///
278 /// The controller resumes a reservation panic while its guard is still
279 /// alive, which poisons this lock. The lock guards no data of its own, and
280 /// such a transaction has already resolved every reservation it held and
281 /// either committed fully or not at all, so the poison is recovered instead
282 /// of propagated: a successor must still be able to mutate the transcript.
283 fn enter_transaction(&self) -> MutexGuard<'_, ()> {
284 #[cfg(test)]
285 probe_transaction_lock(self);
286 self.transaction
287 .lock()
288 .unwrap_or_else(|poisoned| poisoned.into_inner())
289 }
290
291 fn control(&self) -> MutexGuard<'_, Control> {
292 self.control.lock().expect("session control lock poisoned")
293 }
294}
295
296/// A long-lived conversation substrate with a single active lease.
297///
298/// # Panics
299///
300/// A session serializes lease admission and release behind one control lock, and
301/// every operation on a `Session` or its [`Lease`] that consults that lock
302/// propagates a poisoned one rather than recovering it, per the crate-level
303/// [lock-poisoning contract](crate#lock-poisoning). The lock guards only the
304/// active-lease slot, and no foreign code runs while it is held, so nothing a
305/// caller passes can poison it.
306///
307/// The session's separate transcript-transaction lock is the crate's one
308/// deliberate recovery, for the reason that contract records: a mutation is
309/// expected to unwind through it, and a successor must still be able to mutate
310/// the transcript afterwards.
311#[derive(Clone)]
312pub struct Session {
313 inner: Arc<SessionInner>,
314}
315
316impl fmt::Debug for Session {
317 /// Prints the session identity, which is what a session is addressed by.
318 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
319 formatter
320 .debug_struct("Session")
321 .field("id", &self.inner.id)
322 .finish()
323 }
324}
325
326impl Session {
327 /// Creates a session from an optional owned transcript snapshot.
328 ///
329 /// # The seed/live boundary lives with the caller
330 ///
331 /// `seed` is the replayed prefix, so this caller already holds both
332 /// coordinates the boundary can be named in: the prefix length, and the
333 /// [`Version`] the epoch resumes at. Both remain valid as live work
334 /// appends, and a composition layer that forks or resumes keeps whichever
335 /// its own persistence is keyed on.
336 ///
337 /// The transcript stores no such marker, because no core path treats a
338 /// replayed record differently from a live one: projection, the exchange
339 /// grammar and replay validity are all properties of the whole history.
340 /// Recording the boundary here would be storing a number core neither
341 /// produces nor consumes. Session trees, branching and branch replay are
342 /// composition-layer concerns built on top of these two coordinates.
343 #[must_use]
344 pub fn new(id: String, seed: Option<Snapshot>) -> Self {
345 let transcript = seed.map_or_else(Store::new, Store::restore);
346 Self {
347 inner: Arc::new(SessionInner {
348 id,
349 transcript,
350 state: session_state::Store::new(),
351 input_mailbox: InputMailbox::new(),
352 transaction: Mutex::new(()),
353 control: Mutex::new(Control { active: None }),
354 #[cfg(test)]
355 admit_before_control: Mutex::new(None),
356 #[cfg(test)]
357 admit_with_control: Mutex::new(None),
358 #[cfg(test)]
359 commit_overlap: Mutex::new(None),
360 #[cfg(test)]
361 release_probe: Mutex::new(None),
362 #[cfg(test)]
363 transaction_arrivals: Mutex::new(None),
364 }),
365 }
366 }
367
368 /// Returns this session's identity.
369 #[must_use]
370 pub fn id(&self) -> &str {
371 &self.inner.id
372 }
373
374 /// Returns read-only atomic transcript snapshot authority.
375 #[must_use]
376 pub fn transcript(&self) -> SnapshotReader {
377 self.inner.transcript.snapshot_reader()
378 }
379
380 /// Returns read-only owned session-state authority.
381 #[must_use]
382 pub fn state(&self) -> session_state::Reader {
383 self.inner.state.reader()
384 }
385
386 /// Returns the shared asynchronous input mailbox.
387 ///
388 /// **Shared, despite being returned by value.** [`InputMailbox`] is a
389 /// handle: this hands back another one onto *this* Session's queue, so
390 /// pushing to it reaches a Run that is already running, and two calls to
391 /// `input_mailbox` address the same queue.
392 ///
393 /// The queue belongs to the Session, not to its current Run or lease. Releasing
394 /// a lease does not drain unclaimed batches: a successor Run on this Session
395 /// may claim them at their next eligible boundary. Call [`InputMailbox::drain`]
396 /// explicitly before starting that successor when the composition layer wants
397 /// a Run-local queue instead.
398 ///
399 /// That matters because [`InputMailbox::new`] is also public, and a
400 /// mailbox built that way belongs to nobody. Pushing to it succeeds, returns
401 /// nothing, and is never claimed — the one way to inject input and observe
402 /// no error and no effect. If a batch you pushed never arrived, check that it
403 /// went through `session.input_mailbox()`.
404 #[must_use]
405 pub fn input_mailbox(&self) -> InputMailbox {
406 self.inner.input_mailbox.clone()
407 }
408
409 /// Atomically acquires the sole active lease, or returns `None` while busy.
410 ///
411 /// Acquisition waits for any in-flight transcript transaction to resolve, so
412 /// a successor can never observe a committed version whose reservations have
413 /// not yet published.
414 ///
415 /// # Panics
416 ///
417 /// If the session control lock is poisoned, as
418 /// [the session's panic conditions](Session#panics) describe.
419 #[must_use]
420 pub fn try_acquire(&self) -> Option<Lease> {
421 let _transaction = self.inner.enter_transaction();
422 let mut control = self.inner.control();
423 if control.active.is_some() {
424 return None;
425 }
426 let token = Arc::new(LeaseToken { _identity: 0 });
427 control.active = Some(ActiveLease {
428 token: Arc::clone(&token),
429 admitted: false,
430 });
431 Some(Lease {
432 inner: Arc::clone(&self.inner),
433 token,
434 state: self.inner.state.acquire(),
435 })
436 }
437}
438
439/// Exclusive, explicitly admitted mutation authority for one session use.
440pub struct Lease {
441 inner: Arc<SessionInner>,
442 token: Arc<LeaseToken>,
443 state: Writer,
444}
445
446impl fmt::Debug for Lease {
447 /// Prints the session this exclusive authority was taken over.
448 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
449 formatter
450 .debug_struct("Lease")
451 .field("session", &self.inner.id)
452 .finish()
453 }
454}
455
456impl Lease {
457 /// Atomically commits successful admission for this lease.
458 ///
459 /// This is a lifecycle barrier, not a dependency-continuity policy. A
460 /// composition-layer launcher that needs continuity must validate its own
461 /// metadata before calling [`Agent::start`](crate::runtime::agent::Agent::start);
462 /// it cannot share this Session's private control lock.
463 ///
464 /// # Errors
465 ///
466 /// - [`LeaseError::Released`] if this lease is no longer the session's active
467 /// one, which includes a lease that was released and a session that has
468 /// since admitted a successor.
469 /// - [`LeaseError::AlreadyAdmitted`] if this lease already committed
470 /// admission. Admission remains once per lease rather than idempotent.
471 ///
472 /// A failure leaves the admitted flag unchanged.
473 ///
474 /// # Panics
475 ///
476 /// If the session control lock is poisoned, as
477 /// [the session's panic conditions](Session#panics) describe. Admission also
478 /// asserts that the lease it verified under that lock is still the active one
479 /// when it marks it admitted; both hold the same guard, so failing that
480 /// assertion would be a defect in this crate rather than a caller error.
481 pub fn admit(&self) -> Result<(), LeaseError> {
482 #[cfg(test)]
483 pause_at(&self.inner.admit_before_control);
484 let mut control = self.inner.control();
485 if active(&control, &self.token)?.admitted {
486 return Err(LeaseError::AlreadyAdmitted);
487 }
488 #[cfg(test)]
489 pause_at(&self.inner.admit_with_control);
490 control
491 .active
492 .as_mut()
493 .expect("active lease was verified under the same lock")
494 .admitted = true;
495 Ok(())
496 }
497
498 /// Reports whether this still-active lease has synchronously committed admission.
499 ///
500 /// # Panics
501 ///
502 /// If the session control lock is poisoned, as
503 /// [the session's panic conditions](Session#panics) describe.
504 #[must_use]
505 pub fn is_admitted(&self) -> bool {
506 let control = self.inner.control();
507 control
508 .active
509 .as_ref()
510 .is_some_and(|active| Arc::ptr_eq(&active.token, &self.token) && active.admitted)
511 }
512
513 /// Returns this lease's mutable session-state capability.
514 #[must_use]
515 pub const fn state(&self) -> &Writer {
516 &self.state
517 }
518
519 /// Atomically captures the transcript; reads remain valid after release.
520 ///
521 /// # Errors
522 ///
523 /// [`store::Error::Poisoned`] if a transcript writer panicked while holding
524 /// the store lock. Release is deliberately not a failure here: this is a
525 /// read, and the shared immutable snapshot stays usable after the authority
526 /// that captured it is gone.
527 pub fn transcript_snapshot(&self) -> Result<Snapshot, store::Error> {
528 self.inner.transcript.snapshot_reader().snapshot()
529 }
530
531 pub(crate) fn transcript_reader(&self) -> SnapshotReader {
532 self.inner.transcript.snapshot_reader()
533 }
534
535 pub(crate) fn fork_transcript(&self) -> Result<Store, store::Error> {
536 self.inner.transcript.fork()
537 }
538
539 /// Opens the session's sole transcript transaction.
540 ///
541 /// Every transcript mutation, including the reservation controller's
542 /// reserve-commit-publish sequence, runs inside one of these. The returned
543 /// guard is the only route to a compare-and-set, so no caller can commit
544 /// outside the transaction domain, and a second mutation - a direct
545 /// compare-and-set, a release, or a successor acquisition - blocks until this
546 /// transaction resolves.
547 ///
548 /// A reservation callback holds no lease, so it cannot re-enter this
549 /// non-reentrant transaction from inside one.
550 pub(crate) fn begin_transaction(&self) -> Transaction<'_> {
551 Transaction {
552 _transaction: self.inner.enter_transaction(),
553 lease: self,
554 }
555 }
556
557 /// Appends an owned batch only at `expected`, inside its own transaction.
558 ///
559 /// # Errors
560 ///
561 /// [`LeaseError::Released`] if this lease is no longer the session's active
562 /// one, checked before the transcript is touched, so a stale authority never
563 /// mutates history. Otherwise [`LeaseError::Transcript`] carrying whatever
564 /// the store reported: a
565 /// [`VersionConflict`](store::Error::VersionConflict) if another writer
566 /// advanced past `expected`, a
567 /// [`VersionOverflow`](store::Error::VersionOverflow), or a
568 /// [`Poisoned`](store::Error::Poisoned) store. Every one of those leaves the
569 /// history unchanged.
570 ///
571 /// # Panics
572 ///
573 /// If the session control lock is poisoned, as
574 /// [the session's panic conditions](Session#panics) describe. Transcript
575 /// poisoning is reported instead as
576 /// [`LeaseError::Transcript`]`(`[`store::Error::Poisoned`]`)`.
577 pub fn append_batch_if_version(
578 &self,
579 items: Vec<Item>,
580 expected: Version,
581 ) -> Result<Version, LeaseError> {
582 self.begin_transaction()
583 .append_batch_if_version(items, expected)
584 }
585
586 /// Replaces the transcript only at `expected`, inside its own transaction.
587 ///
588 /// # Errors
589 ///
590 /// [`LeaseError::Released`] if this lease is no longer the session's active
591 /// one, or [`LeaseError::Transcript`] carrying a
592 /// [`VersionConflict`](store::Error::VersionConflict),
593 /// [`VersionOverflow`](store::Error::VersionOverflow), or
594 /// [`Poisoned`](store::Error::Poisoned) store. A refused replacement swaps
595 /// nothing, which is what lets a compaction be attempted against a live
596 /// session at all.
597 ///
598 /// # Panics
599 ///
600 /// If the session control lock is poisoned, as
601 /// [the session's panic conditions](Session#panics) describe. Transcript
602 /// poisoning is reported instead as
603 /// [`LeaseError::Transcript`]`(`[`store::Error::Poisoned`]`)`.
604 pub fn replace_if_version(
605 &self,
606 items: Vec<Item>,
607 expected: Version,
608 ) -> Result<Version, LeaseError> {
609 self.begin_transaction().replace_if_version(items, expected)
610 }
611
612 /// Idempotently revokes mutations and makes the session reusable.
613 ///
614 /// Release waits for any in-flight transcript transaction to resolve, so a
615 /// committed mutation always finishes publishing while its authority is
616 /// still live.
617 ///
618 /// # Panics
619 ///
620 /// If the session control lock is poisoned, as
621 /// [the session's panic conditions](Session#panics) describe. Because
622 /// [`Drop`] releases, a poisoned control lock also panics while a `Lease`
623 /// goes out of scope.
624 pub fn release(&self) {
625 let _transaction = self.inner.enter_transaction();
626 self.release_in_transaction();
627 }
628
629 fn release_in_transaction(&self) {
630 #[cfg(test)]
631 probe_control_lock(&self.inner);
632 let mut control = self.inner.control();
633 let owns = control
634 .active
635 .as_ref()
636 .is_some_and(|active| Arc::ptr_eq(&active.token, &self.token));
637 if owns {
638 self.state.release();
639 control.active = None;
640 }
641 }
642}
643
644impl Drop for Lease {
645 fn drop(&mut self) {
646 self.release();
647 }
648}
649
650/// The session's exclusive live transcript-mutation window.
651///
652/// Holding this guard is the sole way to reach a compare-and-set, so the
653/// reservation controller can reserve, commit, and publish without any other
654/// mutation path crossing the sequence. The lock order is always this guard
655/// before the session control lock.
656pub(crate) struct Transaction<'a> {
657 _transaction: MutexGuard<'a, ()>,
658 lease: &'a Lease,
659}
660
661impl Transaction<'_> {
662 /// Reads the live transcript version without materializing the history.
663 ///
664 /// Liveness is verified first, so a released lease cannot observe a version
665 /// it may no longer mutate. The value cannot go stale while this transaction
666 /// is held.
667 pub(crate) fn version(&self) -> Result<Version, LeaseError> {
668 let control = self.lease.inner.control();
669 active(&control, &self.lease.token)?;
670 self.lease
671 .inner
672 .transcript
673 .snapshot_reader()
674 .version()
675 .map_err(LeaseError::Transcript)
676 }
677
678 /// Captures live transcript truth while this transaction excludes mutations.
679 pub(crate) fn snapshot(&self) -> Result<Snapshot, LeaseError> {
680 let control = self.lease.inner.control();
681 active(&control, &self.lease.token)?;
682 self.lease
683 .inner
684 .transcript
685 .snapshot_reader()
686 .snapshot()
687 .map_err(LeaseError::Transcript)
688 }
689
690 /// Appends an owned batch only at `expected`.
691 pub(crate) fn append_batch_if_version(
692 &self,
693 items: Vec<Item>,
694 expected: Version,
695 ) -> Result<Version, LeaseError> {
696 self.commit(|| {
697 self.lease
698 .inner
699 .transcript
700 .appender()
701 .append_batch_if_version(items, expected)
702 })
703 }
704
705 /// Replaces the transcript only at `expected`.
706 pub(crate) fn replace_if_version(
707 &self,
708 items: Vec<Item>,
709 expected: Version,
710 ) -> Result<Version, LeaseError> {
711 self.commit(|| {
712 self.lease
713 .inner
714 .transcript
715 .replacer()
716 .replace_if_version(items, expected)
717 })
718 }
719
720 /// Installs an already-shared replacement only at `expected`.
721 pub(crate) fn install_snapshot(
722 &self,
723 snapshot: Snapshot,
724 expected: Version,
725 ) -> Result<Version, LeaseError> {
726 self.commit(|| {
727 self.lease
728 .inner
729 .transcript
730 .replacer()
731 .install_snapshot_if_version(snapshot, expected)
732 })
733 }
734
735 fn commit<T>(
736 &self,
737 operation: impl FnOnce() -> Result<T, store::Error>,
738 ) -> Result<T, LeaseError> {
739 let control = self.lease.inner.control();
740 active(&control, &self.lease.token)?;
741 #[cfg(test)]
742 pause_at(&self.lease.inner.commit_overlap);
743 operation().map_err(LeaseError::Transcript)
744 }
745}
746
747fn active<'a>(
748 control: &'a Control,
749 token: &Arc<LeaseToken>,
750) -> Result<&'a ActiveLease, LeaseError> {
751 control
752 .active
753 .as_ref()
754 .filter(|active| Arc::ptr_eq(&active.token, token))
755 .ok_or(LeaseError::Released)
756}
757
758#[cfg(test)]
759struct TestOverlap {
760 reached: Barrier,
761 proceed: Barrier,
762}
763
764/// Holds the mailbox lock so a `Debug` must observe contention.
765#[cfg(test)]
766pub(super) fn hold_mailbox_lock(mailbox: &InputMailbox, held: &Barrier, release: &Barrier) {
767 let _guard = mailbox
768 .batches
769 .lock()
770 .expect("injection mailbox lock poisoned");
771 held.wait();
772 release.wait();
773}
774
775#[cfg(test)]
776pub(super) struct TestOverlapControl {
777 overlap: Arc<TestOverlap>,
778 inner: Arc<SessionInner>,
779}
780
781#[cfg(test)]
782impl TestOverlapControl {
783 pub(super) fn wait_until_reached(&self) {
784 self.overlap.reached.wait();
785 }
786
787 pub(super) fn assert_control_is_locked(&self) {
788 assert!(matches!(
789 self.inner.control.try_lock(),
790 Err(TryLockError::WouldBlock)
791 ));
792 }
793
794 pub(super) fn proceed(&self) {
795 self.overlap.proceed.wait();
796 }
797}
798
799#[cfg(test)]
800fn pause_at(slot: &Mutex<Option<Arc<TestOverlap>>>) {
801 let overlap = slot.lock().expect("test overlap lock poisoned").take();
802 if let Some(overlap) = overlap {
803 overlap.reached.wait();
804 overlap.proceed.wait();
805 }
806}
807
808#[cfg(test)]
809fn probe_control_lock(inner: &SessionInner) {
810 let overlap = inner
811 .release_probe
812 .lock()
813 .expect("release probe lock poisoned")
814 .take();
815 if let Some(overlap) = overlap {
816 assert!(matches!(
817 inner.control.try_lock(),
818 Err(TryLockError::WouldBlock)
819 ));
820 overlap.reached.wait();
821 overlap.proceed.wait();
822 }
823}
824
825/// Signals one thread's arrival at an already-held transaction lock.
826///
827/// The probe runs before the arriving thread blocks, and it first proves the
828/// lock is held. A test that observes the signal therefore knows the arriving
829/// mutation cannot make progress until the transaction holder resolves, which is
830/// what makes "this path cannot cross an unresolved transaction" a deterministic
831/// assertion instead of a timing race.
832#[cfg(test)]
833fn probe_transaction_lock(inner: &SessionInner) {
834 let arrival = inner
835 .transaction_arrivals
836 .lock()
837 .expect("transaction arrival lock poisoned")
838 .take();
839 if let Some(arrival) = arrival {
840 assert!(matches!(
841 inner.transaction.try_lock(),
842 Err(TryLockError::WouldBlock)
843 ));
844 arrival
845 .send(())
846 .expect("the installing test observes the arrival");
847 }
848}
849
850/// Observes arrivals at an already-held transaction lock.
851///
852/// The signal is one-shot per [`Self::arm`], so a test can walk several distinct
853/// mutation paths into the same held transaction without a later, unblocked
854/// transaction tripping the probe.
855#[cfg(test)]
856pub(crate) struct TransactionArrival {
857 inner: Arc<SessionInner>,
858 sender: mpsc::Sender<()>,
859 arrived: mpsc::Receiver<()>,
860}
861
862#[cfg(test)]
863impl TransactionArrival {
864 /// Arms the signal for the next single thread to enter a transaction.
865 pub(crate) fn arm(&self) {
866 *self
867 .inner
868 .transaction_arrivals
869 .lock()
870 .expect("transaction arrival lock poisoned") = Some(self.sender.clone());
871 }
872
873 /// Blocks until one armed thread has reached the held transaction lock.
874 pub(crate) fn wait_until_blocked(&self) {
875 self.arrived
876 .recv()
877 .expect("the arriving thread signals before it blocks");
878 }
879}
880
881/// Creates an unarmed arrival probe for one session's transaction lock.
882#[cfg(test)]
883pub(crate) fn install_transaction_arrival(session: &Session) -> TransactionArrival {
884 let (sender, arrived) = mpsc::channel();
885 TransactionArrival {
886 inner: Arc::clone(&session.inner),
887 sender,
888 arrived,
889 }
890}
891
892#[cfg(test)]
893fn install_overlap(
894 session: &Session,
895 slot: &Mutex<Option<Arc<TestOverlap>>>,
896) -> TestOverlapControl {
897 let overlap = Arc::new(TestOverlap {
898 reached: Barrier::new(2),
899 proceed: Barrier::new(2),
900 });
901 *slot.lock().expect("test overlap lock poisoned") = Some(Arc::clone(&overlap));
902 TestOverlapControl {
903 overlap,
904 inner: Arc::clone(&session.inner),
905 }
906}
907
908#[cfg(test)]
909pub(super) fn install_admit_before_control(session: &Session) -> TestOverlapControl {
910 install_overlap(session, &session.inner.admit_before_control)
911}
912
913#[cfg(test)]
914pub(super) fn install_admit_with_control(session: &Session) -> TestOverlapControl {
915 install_overlap(session, &session.inner.admit_with_control)
916}
917
918#[cfg(test)]
919pub(super) fn install_commit_overlap(session: &Session) -> TestOverlapControl {
920 install_overlap(session, &session.inner.commit_overlap)
921}
922
923#[cfg(test)]
924pub(super) fn install_release_probe(session: &Session) -> TestOverlapControl {
925 install_overlap(session, &session.inner.release_probe)
926}