Table of Contents

Class RetentionPolicy

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

How much disk a database's profiling captures may occupy, stored with the data as {name}.typhon/profilings/retention.json (#616, design D-6).

public sealed record RetentionPolicy : IEquatable<RetentionPolicy>
Inheritance
RetentionPolicy
Implements
Inherited Members

Remarks

Policy travels with the data; the writer enforces it. The Workbench is the natural editor of this file, but it is not always present — a game server, a CI box, a customer deployment writes captures with no Workbench installed. A budget only the Workbench honoured would leave those disks filling exactly as before; the surprise would just have moved. So whoever writes a capture prunes first, from this file, with no tooling required.

Pinned captures are counted in the budget and never evicted. Exempting them from the total would make the number a lie precisely when it matters: pin 200 GB and the dashboard still reads "18 of 20 GB" while the disk fills. Counting them keeps the figure honest and the protection identical.

Constructors

RetentionPolicy() 

public RetentionPolicy()

Fields

DefaultBudgetBytes

Default disk budget when a database has no policy file — 20 GiB, the figure the design's worked example uses.

public const long DefaultBudgetBytes = 21474836480

Field Value

long

DefaultKeepLatest

Default number of newest captures kept regardless of budget.

public const int DefaultKeepLatest = 10

Field Value

int

FileName

File name of the policy inside profilings/.

public const string FileName = "retention.json"

Field Value

string

Properties

BudgetBytes

Total bytes the captures in profilings/ may occupy, pinned ones included. Non-positive disables eviction.

public long BudgetBytes { get; init; }

Property Value

long

Default

The built-in policy used when a database has no retention.json.

public static RetentionPolicy Default { get; }

Property Value

RetentionPolicy

KeepLatest

How many of the newest captures survive even when that exceeds BudgetBytes. A floor, not a target: the most recent capture is the one someone is most likely to be about to look at, and a budget that could delete it would make profiling unreliable rather than bounded.

public int KeepLatest { get; init; }

Property Value

int

Pinned

Capture file names (not paths) that must never be evicted. Names keep the directory relocatable — copying or moving a bundle preserves the pins. Unknown entries are ignored, so a pin outlives the capture it named without becoming an error.

public string[] Pinned { get; init; }

Property Value

string[]

Methods

Equals(object?) 

public override bool Equals(object? obj)

Parameters

obj object

Returns

bool

Equals(RetentionPolicy?) 

public bool Equals(RetentionPolicy? other)

Parameters

other RetentionPolicy

Returns

bool

GetHashCode() 

public override int GetHashCode()

Returns

int

IsPinned(string)

True when fileName is pinned. Case-insensitive: the file systems this runs on mostly are.

public bool IsPinned(string fileName)

Parameters

fileName string

Returns

bool

Read(string, out string)

Reads the policy from a profilings/ directory, falling back to Default when the file is absent, empty or unreadable.

public static RetentionPolicy Read(string profilingsDirectory, out string malformedReason)

Parameters

profilingsDirectory string

The database's profilings/ directory.

malformedReason string

Receives why the default was substituted, or null when the file was read successfully or was simply absent.

Returns

RetentionPolicy

Remarks

Never throws. A profiling session must not fail to start because a retention file was hand-edited badly — the capture is the valuable thing and the policy is advice about disk space. malformedReason is non-null when the fallback was taken for a reason worth surfacing (as opposed to the file simply not existing yet), so the caller can log it once.

ToString() 

public override string ToString()

Returns

string

Write(string)

Writes the policy into a profilings/ directory, creating it if needed.

public void Write(string profilingsDirectory)

Parameters

profilingsDirectory string

The database's profilings/ directory.

Operators

operator ==(RetentionPolicy?, RetentionPolicy?) 

public static bool operator ==(RetentionPolicy? left, RetentionPolicy? right)

Parameters

left RetentionPolicy
right RetentionPolicy

Returns

bool

operator !=(RetentionPolicy?, RetentionPolicy?) 

public static bool operator !=(RetentionPolicy? left, RetentionPolicy? right)

Parameters

left RetentionPolicy
right RetentionPolicy

Returns

bool