use std::collections::VecDeque;
use std::error::Error;
use std::fmt;
use std::sync::{Arc, Mutex, MutexGuard};
#[cfg(test)]
use std::sync::{Barrier, TryLockError, mpsc};
use crate::redact::Locked;
use crate::state::session_state::{self, Writer};
use crate::transcript::item::Item;
use crate::transcript::store::{self, Snapshot, SnapshotReader, Store, Version};
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum LeaseError {
Released,
AlreadyAdmitted,
Transcript(store::Error),
}
impl fmt::Display for LeaseError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Released => formatter.write_str("session lease released"),
Self::AlreadyAdmitted => formatter.write_str("session lease already admitted"),
Self::Transcript(error) => error.fmt(formatter),
}
}
}
impl Error for LeaseError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Transcript(error) => Some(error),
Self::Released | Self::AlreadyAdmitted => None,
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum InputTarget {
NextStep,
NextTurn,
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct EmptyInputBatchError;
impl fmt::Display for EmptyInputBatchError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("input batch must not be empty")
}
}
impl Error for EmptyInputBatchError {}
#[derive(Clone)]
pub struct InputBatch {
target: InputTarget,
items: Vec<Item>,
enqueue_sequence: u64,
}
impl fmt::Debug for InputBatch {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("InputBatch")
.field("target", &self.target)
.field("items", &self.items)
.finish()
}
}
impl InputBatch {
pub fn new(target: InputTarget, items: Vec<Item>) -> Result<Self, EmptyInputBatchError> {
if items.is_empty() {
return Err(EmptyInputBatchError);
}
Ok(Self {
target,
items,
enqueue_sequence: 0,
})
}
#[must_use]
pub const fn target(&self) -> InputTarget {
self.target
}
#[must_use]
pub fn items(&self) -> &[Item] {
&self.items
}
#[must_use]
pub fn into_parts(self) -> (InputTarget, Vec<Item>) {
(self.target, self.items)
}
}
#[derive(Clone, Default)]
pub struct InputMailbox {
batches: Arc<Mutex<Queue>>,
}
#[derive(Default)]
struct Queue {
next: u64,
entries: VecDeque<InputBatch>,
}
impl fmt::Debug for InputMailbox {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut mailbox = formatter.debug_struct("InputMailbox");
match self.batches.try_lock() {
Ok(queue) => mailbox.field("batches", &queue.entries.len()),
Err(_contended_or_poisoned) => mailbox.field("batches", &Locked),
}
.finish()
}
}
impl InputMailbox {
#[must_use]
pub fn new() -> Self {
Self::default()
}
pub fn push(&self, mut batch: InputBatch) {
let mut queue = self.lock();
batch.enqueue_sequence = queue.next;
queue.next += 1;
queue.entries.push_back(batch);
}
#[must_use]
pub fn claim(&self, target: InputTarget) -> Option<InputBatch> {
self.take(target)
}
pub(crate) fn claim_conserved(&self, target: InputTarget) -> Option<Claim<'_>> {
self.take(target).map(|batch| Claim {
mailbox: self,
batch: Some(batch),
})
}
fn take(&self, target: InputTarget) -> Option<InputBatch> {
let mut queue = self.lock();
let index = queue
.entries
.iter()
.position(|batch| batch.target == target)?;
queue.entries.remove(index)
}
fn restore(&self, batch: InputBatch) {
let mut queue = self.lock();
let index = queue
.entries
.partition_point(|queued| queued.enqueue_sequence < batch.enqueue_sequence);
queue.entries.insert(index, batch);
}
#[must_use]
pub fn drain(&self) -> Vec<InputBatch> {
self.lock().entries.drain(..).collect()
}
#[must_use]
pub fn len(&self) -> usize {
self.lock().entries.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.len() == 0
}
fn lock(&self) -> MutexGuard<'_, Queue> {
self.batches
.lock()
.expect("injection mailbox lock poisoned")
}
}
pub(crate) struct Claim<'a> {
mailbox: &'a InputMailbox,
batch: Option<InputBatch>,
}
impl Claim<'_> {
pub(crate) const fn batch(&self) -> &InputBatch {
self.batch
.as_ref()
.expect("an unsettled claim holds its batch")
}
pub(crate) const fn settle(&mut self) -> InputBatch {
self.batch.take().expect("a claim settles at most once")
}
}
impl Drop for Claim<'_> {
fn drop(&mut self) {
if let Some(batch) = self.batch.take() {
self.mailbox.restore(batch);
}
}
}
struct LeaseToken {
_identity: u8,
}
struct ActiveLease {
token: Arc<LeaseToken>,
admitted: bool,
}
struct Control {
active: Option<ActiveLease>,
}
struct SessionInner {
id: String,
transcript: Store,
state: session_state::Store,
input_mailbox: InputMailbox,
transaction: Mutex<()>,
control: Mutex<Control>,
#[cfg(test)]
admit_before_control: Mutex<Option<Arc<TestOverlap>>>,
#[cfg(test)]
admit_with_control: Mutex<Option<Arc<TestOverlap>>>,
#[cfg(test)]
commit_overlap: Mutex<Option<Arc<TestOverlap>>>,
#[cfg(test)]
release_probe: Mutex<Option<Arc<TestOverlap>>>,
#[cfg(test)]
transaction_arrivals: Mutex<Option<mpsc::Sender<()>>>,
}
impl SessionInner {
fn enter_transaction(&self) -> MutexGuard<'_, ()> {
#[cfg(test)]
probe_transaction_lock(self);
self.transaction
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
}
fn control(&self) -> MutexGuard<'_, Control> {
self.control.lock().expect("session control lock poisoned")
}
}
#[derive(Clone)]
pub struct Session {
inner: Arc<SessionInner>,
}
impl fmt::Debug for Session {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Session")
.field("id", &self.inner.id)
.finish()
}
}
impl Session {
#[must_use]
pub fn new(id: String, seed: Option<Snapshot>) -> Self {
let transcript = seed.map_or_else(Store::new, Store::restore);
Self {
inner: Arc::new(SessionInner {
id,
transcript,
state: session_state::Store::new(),
input_mailbox: InputMailbox::new(),
transaction: Mutex::new(()),
control: Mutex::new(Control { active: None }),
#[cfg(test)]
admit_before_control: Mutex::new(None),
#[cfg(test)]
admit_with_control: Mutex::new(None),
#[cfg(test)]
commit_overlap: Mutex::new(None),
#[cfg(test)]
release_probe: Mutex::new(None),
#[cfg(test)]
transaction_arrivals: Mutex::new(None),
}),
}
}
#[must_use]
pub fn id(&self) -> &str {
&self.inner.id
}
#[must_use]
pub fn transcript(&self) -> SnapshotReader {
self.inner.transcript.snapshot_reader()
}
#[must_use]
pub fn state(&self) -> session_state::Reader {
self.inner.state.reader()
}
#[must_use]
pub fn input_mailbox(&self) -> InputMailbox {
self.inner.input_mailbox.clone()
}
#[must_use]
pub fn try_acquire(&self) -> Option<Lease> {
let _transaction = self.inner.enter_transaction();
let mut control = self.inner.control();
if control.active.is_some() {
return None;
}
let token = Arc::new(LeaseToken { _identity: 0 });
control.active = Some(ActiveLease {
token: Arc::clone(&token),
admitted: false,
});
Some(Lease {
inner: Arc::clone(&self.inner),
token,
state: self.inner.state.acquire(),
})
}
}
pub struct Lease {
inner: Arc<SessionInner>,
token: Arc<LeaseToken>,
state: Writer,
}
impl fmt::Debug for Lease {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Lease")
.field("session", &self.inner.id)
.finish()
}
}
impl Lease {
pub fn admit(&self) -> Result<(), LeaseError> {
#[cfg(test)]
pause_at(&self.inner.admit_before_control);
let mut control = self.inner.control();
if active(&control, &self.token)?.admitted {
return Err(LeaseError::AlreadyAdmitted);
}
#[cfg(test)]
pause_at(&self.inner.admit_with_control);
control
.active
.as_mut()
.expect("active lease was verified under the same lock")
.admitted = true;
Ok(())
}
#[must_use]
pub fn is_admitted(&self) -> bool {
let control = self.inner.control();
control
.active
.as_ref()
.is_some_and(|active| Arc::ptr_eq(&active.token, &self.token) && active.admitted)
}
#[must_use]
pub const fn state(&self) -> &Writer {
&self.state
}
pub fn transcript_snapshot(&self) -> Result<Snapshot, store::Error> {
self.inner.transcript.snapshot_reader().snapshot()
}
pub(crate) fn transcript_reader(&self) -> SnapshotReader {
self.inner.transcript.snapshot_reader()
}
pub(crate) fn fork_transcript(&self) -> Result<Store, store::Error> {
self.inner.transcript.fork()
}
pub(crate) fn begin_transaction(&self) -> Transaction<'_> {
Transaction {
_transaction: self.inner.enter_transaction(),
lease: self,
}
}
pub fn append_batch_if_version(
&self,
items: Vec<Item>,
expected: Version,
) -> Result<Version, LeaseError> {
self.begin_transaction()
.append_batch_if_version(items, expected)
}
pub fn replace_if_version(
&self,
items: Vec<Item>,
expected: Version,
) -> Result<Version, LeaseError> {
self.begin_transaction().replace_if_version(items, expected)
}
pub fn release(&self) {
let _transaction = self.inner.enter_transaction();
self.release_in_transaction();
}
fn release_in_transaction(&self) {
#[cfg(test)]
probe_control_lock(&self.inner);
let mut control = self.inner.control();
let owns = control
.active
.as_ref()
.is_some_and(|active| Arc::ptr_eq(&active.token, &self.token));
if owns {
self.state.release();
control.active = None;
}
}
}
impl Drop for Lease {
fn drop(&mut self) {
self.release();
}
}
pub(crate) struct Transaction<'a> {
_transaction: MutexGuard<'a, ()>,
lease: &'a Lease,
}
impl Transaction<'_> {
pub(crate) fn version(&self) -> Result<Version, LeaseError> {
let control = self.lease.inner.control();
active(&control, &self.lease.token)?;
self.lease
.inner
.transcript
.snapshot_reader()
.version()
.map_err(LeaseError::Transcript)
}
pub(crate) fn snapshot(&self) -> Result<Snapshot, LeaseError> {
let control = self.lease.inner.control();
active(&control, &self.lease.token)?;
self.lease
.inner
.transcript
.snapshot_reader()
.snapshot()
.map_err(LeaseError::Transcript)
}
pub(crate) fn append_batch_if_version(
&self,
items: Vec<Item>,
expected: Version,
) -> Result<Version, LeaseError> {
self.commit(|| {
self.lease
.inner
.transcript
.appender()
.append_batch_if_version(items, expected)
})
}
pub(crate) fn replace_if_version(
&self,
items: Vec<Item>,
expected: Version,
) -> Result<Version, LeaseError> {
self.commit(|| {
self.lease
.inner
.transcript
.replacer()
.replace_if_version(items, expected)
})
}
pub(crate) fn install_snapshot(
&self,
snapshot: Snapshot,
expected: Version,
) -> Result<Version, LeaseError> {
self.commit(|| {
self.lease
.inner
.transcript
.replacer()
.install_snapshot_if_version(snapshot, expected)
})
}
fn commit<T>(
&self,
operation: impl FnOnce() -> Result<T, store::Error>,
) -> Result<T, LeaseError> {
let control = self.lease.inner.control();
active(&control, &self.lease.token)?;
#[cfg(test)]
pause_at(&self.lease.inner.commit_overlap);
operation().map_err(LeaseError::Transcript)
}
}
fn active<'a>(
control: &'a Control,
token: &Arc<LeaseToken>,
) -> Result<&'a ActiveLease, LeaseError> {
control
.active
.as_ref()
.filter(|active| Arc::ptr_eq(&active.token, token))
.ok_or(LeaseError::Released)
}
#[cfg(test)]
struct TestOverlap {
reached: Barrier,
proceed: Barrier,
}
#[cfg(test)]
pub(super) fn hold_mailbox_lock(mailbox: &InputMailbox, held: &Barrier, release: &Barrier) {
let _guard = mailbox
.batches
.lock()
.expect("injection mailbox lock poisoned");
held.wait();
release.wait();
}
#[cfg(test)]
pub(super) struct TestOverlapControl {
overlap: Arc<TestOverlap>,
inner: Arc<SessionInner>,
}
#[cfg(test)]
impl TestOverlapControl {
pub(super) fn wait_until_reached(&self) {
self.overlap.reached.wait();
}
pub(super) fn assert_control_is_locked(&self) {
assert!(matches!(
self.inner.control.try_lock(),
Err(TryLockError::WouldBlock)
));
}
pub(super) fn proceed(&self) {
self.overlap.proceed.wait();
}
}
#[cfg(test)]
fn pause_at(slot: &Mutex<Option<Arc<TestOverlap>>>) {
let overlap = slot.lock().expect("test overlap lock poisoned").take();
if let Some(overlap) = overlap {
overlap.reached.wait();
overlap.proceed.wait();
}
}
#[cfg(test)]
fn probe_control_lock(inner: &SessionInner) {
let overlap = inner
.release_probe
.lock()
.expect("release probe lock poisoned")
.take();
if let Some(overlap) = overlap {
assert!(matches!(
inner.control.try_lock(),
Err(TryLockError::WouldBlock)
));
overlap.reached.wait();
overlap.proceed.wait();
}
}
#[cfg(test)]
fn probe_transaction_lock(inner: &SessionInner) {
let arrival = inner
.transaction_arrivals
.lock()
.expect("transaction arrival lock poisoned")
.take();
if let Some(arrival) = arrival {
assert!(matches!(
inner.transaction.try_lock(),
Err(TryLockError::WouldBlock)
));
arrival
.send(())
.expect("the installing test observes the arrival");
}
}
#[cfg(test)]
pub(crate) struct TransactionArrival {
inner: Arc<SessionInner>,
sender: mpsc::Sender<()>,
arrived: mpsc::Receiver<()>,
}
#[cfg(test)]
impl TransactionArrival {
pub(crate) fn arm(&self) {
*self
.inner
.transaction_arrivals
.lock()
.expect("transaction arrival lock poisoned") = Some(self.sender.clone());
}
pub(crate) fn wait_until_blocked(&self) {
self.arrived
.recv()
.expect("the arriving thread signals before it blocks");
}
}
#[cfg(test)]
pub(crate) fn install_transaction_arrival(session: &Session) -> TransactionArrival {
let (sender, arrived) = mpsc::channel();
TransactionArrival {
inner: Arc::clone(&session.inner),
sender,
arrived,
}
}
#[cfg(test)]
fn install_overlap(
session: &Session,
slot: &Mutex<Option<Arc<TestOverlap>>>,
) -> TestOverlapControl {
let overlap = Arc::new(TestOverlap {
reached: Barrier::new(2),
proceed: Barrier::new(2),
});
*slot.lock().expect("test overlap lock poisoned") = Some(Arc::clone(&overlap));
TestOverlapControl {
overlap,
inner: Arc::clone(&session.inner),
}
}
#[cfg(test)]
pub(super) fn install_admit_before_control(session: &Session) -> TestOverlapControl {
install_overlap(session, &session.inner.admit_before_control)
}
#[cfg(test)]
pub(super) fn install_admit_with_control(session: &Session) -> TestOverlapControl {
install_overlap(session, &session.inner.admit_with_control)
}
#[cfg(test)]
pub(super) fn install_commit_overlap(session: &Session) -> TestOverlapControl {
install_overlap(session, &session.inner.commit_overlap)
}
#[cfg(test)]
pub(super) fn install_release_probe(session: &Session) -> TestOverlapControl {
install_overlap(session, &session.inner.release_probe)
}