Class PagedMMFOptions

Namespace

Typhon.Engine

Assembly

Typhon.Engine.dll

Configuration for a Typhon.Engine.Internals.PagedMMF / Typhon.Engine.Internals.ManagedPagedMMF store: which database (name + directory), how large the page cache is, and a couple of diagnostics. A Typhon database is a single on-disk bundle directory (BundleDirectory); these options locate and size it.

public class PagedMMFOptions

Inheritance

object

PagedMMFOptions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

PagedMMFOptions()

public PagedMMFOptions()

Fields

DatabaseNameMaxUtf8Size

Maximum length, in UTF-8 bytes, allowed for DatabaseName and DatabaseFileName.

public const int DatabaseNameMaxUtf8Size = 63

Field Value

int

DefaultCacheSizeBytes

The default DatabaseCacheSize in bytes (256 MiB) — the value used when it is not set explicitly.

public const ulong DefaultCacheSizeBytes = 268435456

Field Value

ulong

MinimumCacheSizeBytes

The minimum permitted DatabaseCacheSize in bytes (8 MiB). Values below this fail validation.

public const ulong MinimumCacheSizeBytes = 8388608

Field Value

ulong

PageSizeBytes

The page size in bytes (8 KiB). DatabaseCacheSize must be a multiple of this.

public const int PageSizeBytes = 8192

Field Value

int

Properties

BundleDirectory

The database bundle directory — {DatabaseDirectory}/{DatabaseName}.typhon. A Typhon database is this single directory; the paged data file (data), the single-writer lock (db.lock), and the WAL segment directory (wal/) all live inside it. See claude/design/Storage/typhon-bundle-format.md.

public string BundleDirectory { get; }

Property Value

string

DatabaseAbsoluteDirectory

The absolute form of DatabaseDirectory.

public string DatabaseAbsoluteDirectory { get; }

Property Value

string

DatabaseCacheSize

Page-cache size, in bytes. Must be a multiple of PageSizeBytes and at least MinimumCacheSizeBytes; at most 2³¹ − 1 pages (about 16 TiB). No other ceiling (#945): past what the host grants, the allocation is refused at startup with a StorageException (PageCacheAllocationFailed) — on Windows the commit limit (RAM plus page file), on Linux the kernel's overcommit policy. Default: DefaultCacheSizeBytes (256 MiB). The cache is one native allocation, so size it for one primary engine per process; a workload whose transaction working set exceeds the cache hits PageCacheBackpressureTimeoutException. Prefer the fluent TyphonOptions.PageCacheSize(...) to set it.

public ulong DatabaseCacheSize { get; set; }

Property Value

ulong

DatabaseDirectory

Directory that contains the database bundle. Default: the current working directory.

public string DatabaseDirectory { get; set; }

Property Value

string

DatabaseFileName

Configured database file-name prefix; falls back to DatabaseName when unset. Subject to the same character and length rules.

public string DatabaseFileName { get; set; }

Property Value

string

DatabaseName

The database name — also the stem of the bundle directory (BundleDirectory). Must match ^[A-Za-z0-9_-]+$ and fit within DatabaseNameMaxUtf8Size UTF-8 bytes. Default: TyphonDB.

public string DatabaseName { get; set; }

Property Value

string

FreeQuarantineCacheFraction

The share of DatabaseCacheSize that freed revision and content chunks of Versioned components may occupy, held back from reuse, before the engine asks for a checkpoint. Default 0.125. A freed chunk is reused only once a checkpoint has written the pages that stopped naming it — until then the data file may still name it, and a crash would recover the old owner's chain over the new owner's data (#1251). Held chunks stay allocated: lower values checkpoint more often under heavy updates, higher values let segments grow further between checkpoints.

public double FreeQuarantineCacheFraction { get; set; }

Property Value

double

IsValid

Whether the current configuration passes validation (name, directory, and cache-size rules). true when every rule holds.

public bool IsValid { get; }

Property Value

bool

LockHandoffTimeout

How long to wait for a yieldable holder to release before giving up. Default 5 seconds.

public TimeSpan LockHandoffTimeout { get; set; }

Property Value

TimeSpan

Remarks

Only ever consumed when the incumbent advertised YieldableLock; a non-yieldable lock still fails instantly. Kept short deliberately — the cost of the feature being on is that a hung observer turns an instant failure into this much waiting, so it must stay below the threshold where a developer starts wondering whether their app has frozen. Set to Zero to opt out and fail fast even against an observer.

PagesDebugPattern

When true, fills a page-cache slot with a recognizable debug pattern when it is assigned. Default false. No longer observable (PS-14, #1126): a page not read from disk is cleared right after, and a page read from disk is overwritten by the read.

public bool PagesDebugPattern { get; set; }

Property Value

bool

VerifyOnOpen

How much of the database to verify when opening it. Defaults to Spine.

public OpenVerification VerifyOnOpen { get; set; }

Property Value

OpenVerification

Remarks

The clean-shutdown flag records that the last process closed properly. It does not record that the bytes are still correct. Damage that happens while a database is closed — bit rot, a truncated copy, a restore from the wrong place, a file-level backup tool writing through — is invisible to a clean open, which then proceeds to serve it.

Spine is the tier that earns being always on: it is bounded by the number of segments rather than the size of the database, so it reads kilobytes and costs well under a millisecond, and it catches the entire structurally-broken class — which is precisely the damage where opening anyway does the most harm, because the engine then follows directory pointers into garbage.

YieldableLock

Advertise this holder as willing to release the database on request (#621). Default false.

public bool YieldableLock { get; set; }

Property Value

bool

Remarks

Set by long-lived read-only observers — the Workbench — and by nothing else. It is written into db.lock as yieldable, and it is the holder's advertisement that enables handoff, never the claimant's configuration. That asymmetry is what makes the feature safe to have on by default: two ordinary application instances contend exactly as they always did, because the incumbent advertised nothing.

Advertising it is a promise. A process that sets this must actually watch for RequestFileName and dispose its engine when one appears; one that advertises and then ignores requests merely converts an immediate failure into a short wait followed by the same failure.

Methods

EnsureFileDeleted()

Deletes the entire database bundle directory (BundleDirectory) — data file, lock, and WAL. A Typhon database is one directory, so "delete the database" is a single recursive directory delete. Must only be called when the database is closed: an open data handle would block the recursive delete (the throw is swallowed, potentially leaving a half-deleted bundle).

public void EnsureFileDeleted()