Class UnitOfWork

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

The durability boundary for user operations. Batches multiple transactions for efficient persistence while maintaining atomicity guarantees on crash recovery. Each UoW is assigned a UoW ID that stamps all revisions created within its scope.

public sealed class UnitOfWork : IDisposable

Inheritance

object

UnitOfWork

Implements

IDisposable

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This is the middle tier of the three-tier API hierarchy: DatabaseEngine → UnitOfWork → Transaction. Create via CreateUnitOfWork(DurabilityMode, TimeSpan).

All durability modes route through the WAL (WAL is mandatory — ADR-054); DurabilityMode controls only WHEN a UoW's WAL records become crash-safe:

• Deferred: records become durable only on an explicit Flush() / FlushAsync(); dispose does not flush.
• GroupCommit: the WAL writer thread auto-flushes buffered records every GroupCommitIntervalMs; FlushAsync() waits for the pending group.
• Immediate: each Commit() requests a WAL flush and waits for FUA durability before returning.

Dirty data pages are drained by the checkpoint in every mode — never by a per-UoW SaveChanges.

Properties

CommittedTransactionCount

Number of transactions that have been committed within this UoW.

public int CommittedTransactionCount { get; }

Property Value

int

DurabilityMode

Controls when WAL records become crash-safe for this UoW.

public DurabilityMode DurabilityMode { get; }

Property Value

DurabilityMode

IsDisposed

Whether this UoW has been disposed.

public bool IsDisposed { get; }

Property Value

bool

State

Current lifecycle state of this UoW.

public UnitOfWorkState State { get; }

Property Value

UnitOfWorkState

TransactionCount

Number of transactions created within this UoW.

public int TransactionCount { get; }

Property Value

int

UowId

UoW identifier for revision stamping and crash recovery. Allocated from UoW Registry.

public ushort UowId { get; }

Property Value

ushort

Methods

CreateContext(TimeSpan)

Creates a UnitOfWorkContext for use with Commit(ref UnitOfWorkContext, ConcurrencyConflictHandler). Composes the UoW's deadline with the provided timeout (tighter deadline wins).

public UnitOfWorkContext CreateContext(TimeSpan timeout = default)

Parameters

timeout TimeSpan

Returns

UnitOfWorkContext

CreateTransaction(DurabilityDiscipline)

Creates a new transaction within this UoW. The transaction inherits the UoW's identity and deadline for revision stamping and cancellation propagation.

public Transaction CreateTransaction(DurabilityDiscipline discipline = DurabilityDiscipline.TickFence)

Parameters

discipline DurabilityDiscipline

Durability discipline for SingleVersion-layout writes (TickFence default, or Commit for zero-loss, atomic, commit-scoped writes). Fixed for the transaction.

Returns

Transaction

Exceptions

ObjectDisposedException

The UoW has been disposed.

InvalidOperationException

The UoW is not in Pending state.

Dispose()

public void Dispose()

Flush()

Synchronous flush: signals the WAL writer and waits for this UoW's records to reach the durable LSN, then transitions the UoW to WalDurable. No-op when the UoW is no longer Pending. WAL is mandatory (ADR-054).

public void Flush()

FlushAsync()

Async flush. WAL is mandatory: signals the WAL writer and waits for the durable LSN.

public Task FlushAsync()

Returns

Task