Skip to content
Orleans logoMicrosoft Orleans

IJournalStorage

interface

Namespace: Orleans.Journaling

Provides journal storage. 
public interface IJournalStorage

Remarks

A journal is an ordered sequence of segments. Each successful IJournalStorage adds one segment to the end, and each successful IJournalStorage replaces the whole journal with one segment. The journal is the source of truth for journaled state, so every implementation provides the following guarantees.

Callers await each operation before starting another operation through the same storage instance. Separate instances coordinate through the storage provider's write preconditions.

  • All-or-nothing writes.IJournalStorage and IJournalStorage make the whole segment visible at once or none of it. Successful reads observe whole segments after a process or storage crash, a timeout, a precondition conflict, or a retry inside the provider. A segment which the provider stores across several records or requests becomes visible through one atomic publication step.
  • Limits fail the whole call. A segment which exceeds a provider limit, such as a maximum request, block, transaction, or value size, fails the call with an exception, and nothing of it becomes visible.
  • Failure outcomes. A definitively rejected write, such as a locally detected limit or invalid input, preserves the earlier content. After a request has an indeterminate outcome, such as a timeout or a lost response, the segment was written whole or not at all. A retry can report a precondition conflict after the original request committed, so recovery determines the outcome even when the final exception is InconsistentStateException. After any failed write, the journaled state manager fences itself and recovers its state from a fresh read.
  • Whole, ordered reads. A successful IJournalStorage returns the content of one version of the journal: every segment written up to that version, whole and in write order, and nothing of any later write. Callers discard data delivered by a failed read and recover from the beginning.
  • Write precondition. Each storage instance holds a write precondition established by its first successful IJournalStorage or creation, including an observed absence, and advanced by its own writes. IJournalStorage, IJournalStorage, and IJournalStorage succeed only if the journal is still at that version, so a write after observing an absent journal requires the journal to still be absent. Otherwise they throw InconsistentStateException; each conflicting request leaves storage unchanged. A successful write, including creating the journal with IJournalStorage, advances the precondition to the version it produced. Callers read the journal, or create it, before writing through an instance: a write through an instance which has done neither throws System.InvalidOperationException. Metadata operations never establish or move the precondition, and metadata-only updates never change the journal's content.

Subsequent reads require the journal to match the instance's established precondition and throw InconsistentStateException on a content change. A caller can therefore reread its own journal for history or compaction while preserving its write precondition. Recovery after a conflict uses a fresh storage instance.

Properties

Methods