Table of Contents

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
PagedMMFOptions
Inherited Members

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, at least MinimumCacheSizeBytes, and at most 4 GiB. Default: DefaultCacheSizeBytes (256 MiB). The cache is a GCHandle-pinned byte array, 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

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 newly-allocated pages with a recognizable debug pattern (development/testing). Default false.

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()