lifecycle

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputeSafeFloor 

func ComputeSafeFloor(oldestReaderVersion, ttlBoundVersion, maxVersionsBoundVersion, previousFloor storage.MVCCVersion) storage.MVCCVersion

ComputeSafeFloor returns a monotonic safe floor from runtime and retention bounds.

func PriorityScore 

func PriorityScore(debtBytes int64, tombstoneDepth int, keyHotness float64, keyAge time.Duration) float64

PriorityScore computes a debt-first score.

func TTLBoundVersion 

func TTLBoundVersion(ttl time.Duration) storage.MVCCVersion

TTLBoundVersion returns the version bound for TTL-based retention.

Types

type ApplyResult 

type ApplyResult struct {
	KeysProcessed       int
	VersionsDeleted     int64
	BytesFreed          int64
	FenceMismatches     int
	HotContentionKeys   int
	NamespaceBytesFreed map[string]int64
}

ApplyResult summarizes one apply pass.

type CostEstimate 

type CostEstimate struct {
	IteratorSeeks  int
	ValueLogReads  int
	BytesRewritten int64
}

CostEstimate holds coarse compaction cost proxies.

func EstimateCost 

func EstimateCost(entry PrunePlanEntry) CostEstimate

EstimateCost returns a rough cost for applying an entry.

type EmergencyConfig 

type EmergencyConfig struct {
	DebtGrowthSlopeThreshold float64
	MaxCPUShare              float64
	MaxIOBudgetBytesPerCycle int64
	MaxRuntimePerCycle       time.Duration
}

EmergencyConfig controls emergency-mode activation.

type EmergencyController 

type EmergencyController struct {
	// contains filtered or unexported fields
}

EmergencyController activates emergency behavior when debt grows too quickly.

func NewEmergencyController 

func NewEmergencyController(config EmergencyConfig) *EmergencyController

NewEmergencyController creates a controller.

func (*EmergencyController) AdjustCompactionBudget 

func (e *EmergencyController) AdjustCompactionBudget(base LifecycleConfig) LifecycleConfig

AdjustCompactionBudget tightens admission and raises pruning intensity within resource ceilings.

func (*EmergencyController) Evaluate 

func (e *EmergencyController) Evaluate() bool

Evaluate updates and returns the emergency state.

func (*EmergencyController) IsActive 

func (e *EmergencyController) IsActive() bool

IsActive returns whether emergency mode is active.

func (*EmergencyController) RecordDebt 

func (e *EmergencyController) RecordDebt(bytes int64)

RecordDebt appends a debt sample.

func (*EmergencyController) SetCritical 

func (e *EmergencyController) SetCritical(critical bool)

SetCritical marks whether the current pressure band is critical.

type LifecycleConfig 

type LifecycleConfig struct {
	Enabled                     bool
	CycleInterval               time.Duration
	MaxVersionsPerKey           int
	TTL                         time.Duration
	MaxChainHardCap             int
	HighEnterBytes              int64
	HighExitBytes               int64
	CriticalEnterBytes          int64
	CriticalExitBytes           int64
	PressureEnterWindow         time.Duration
	PressureExitWindow          time.Duration
	MaxSnapshotLifetime         time.Duration
	MaxCPUShare                 float64
	MaxIOBudgetBytesPerInterval int64
	MaxRuntimePerCycle          time.Duration
	FenceRetryInitialDelay      time.Duration
	FenceRetryMaxDelay          time.Duration
	FenceRetryPerKeyLimit       int
	FenceRetryCrossRunLimit     int
	FenceRetryCooldown          time.Duration
	DebtSampleFraction          float64
	FullScanEveryNCycles        int
	NamespaceBudgets            map[string]NamespaceBudget
	DebtGrowthSlopeThreshold    float64
}

LifecycleConfig controls MVCC lifecycle manager behavior.

func DefaultLifecycleConfig 

func DefaultLifecycleConfig() LifecycleConfig

DefaultLifecycleConfig returns the baseline lifecycle configuration.

type LifecycleMetrics 

type LifecycleMetrics struct {
	BytesPinnedByOldestReader atomic.Int64
	CompactionDebtBytes       atomic.Int64
	CompactionDebtKeys        atomic.Int64
	GracefulReaderExpires     atomic.Int64
	HardReaderExpires         atomic.Int64
	PrunableBytesTotal        atomic.Int64
	PrunedBytesTotal          atomic.Int64
	TombstoneChainMaxDepth    atomic.Int64
	FloorLagVersions          atomic.Int64
	PruneRunKeysScannedTotal  atomic.Int64
	PruneStalePlanSkipsTotal  atomic.Int64
	// contains filtered or unexported fields
}

LifecycleMetrics stores lifecycle counters and the last-run summary.

func NewLifecycleMetrics 

func NewLifecycleMetrics() *LifecycleMetrics

NewLifecycleMetrics allocates lifecycle counters.

func (*LifecycleMetrics) AddNamespacePrunedBytes 

func (m *LifecycleMetrics) AddNamespacePrunedBytes(namespace string, bytesFreed int64)

AddNamespacePrunedBytes increments pruned-byte counters for one namespace.

func (*LifecycleMetrics) RecordPruneRun 

func (m *LifecycleMetrics) RecordPruneRun(result ApplyResult, duration time.Duration)

RecordPruneRun stores the last run summary and increments counters.

func (*LifecycleMetrics) RecordReaderExpiration 

func (m *LifecycleMetrics) RecordReaderExpiration(graceful bool, hard bool)

RecordReaderExpiration increments expiration counters for forced reader shutdowns.

func (*LifecycleMetrics) ReplaceNamespaceDebt 

func (m *LifecycleMetrics) ReplaceNamespaceDebt(summaries map[string]NamespaceDebtSummary)

ReplaceNamespaceDebt replaces namespace debt gauges for the latest plan snapshot.

func (*LifecycleMetrics) ToMap 

func (m *LifecycleMetrics) ToMap(registry *ReaderRegistry) map[string]interface{}

ToMap renders status-ready lifecycle metrics.

func (*LifecycleMetrics) TopDebtKeys 

func (m *LifecycleMetrics) TopDebtKeys(limit int) []storage.MVCCLifecycleDebtKey

TopDebtKeys returns the highest-debt logical keys from the latest evaluated plan.

func (*LifecycleMetrics) UpdateDebt 

func (m *LifecycleMetrics) UpdateDebt(debtBytes int64, debtKeys int64)

UpdateDebt replaces current debt counters.

func (*LifecycleMetrics) UpdatePinnedBytes 

func (m *LifecycleMetrics) UpdatePinnedBytes(bytes int64)

UpdatePinnedBytes updates the pinned-byte gauge.

func (*LifecycleMetrics) UpdatePlanInsights 

func (m *LifecycleMetrics) UpdatePlanInsights(plan *PrunePlan)

UpdatePlanInsights refreshes derived gauges from the latest plan.

type LifecycleStorageEngine 

type LifecycleStorageEngine interface {
	IterateMVCCHeads(ctx context.Context, yield func(logicalKey []byte, head storage.MVCCHead) error) error
	IterateMVCCVersions(ctx context.Context, logicalKey []byte, yield func(version storage.MVCCVersion, tombstoned bool, sizeBytes int64) error) error
	DeleteMVCCVersion(ctx context.Context, logicalKey []byte, version storage.MVCCVersion) error
	WriteMVCCHead(ctx context.Context, logicalKey []byte, head storage.MVCCHead) error
	ReadMVCCHead(ctx context.Context, logicalKey []byte) (storage.MVCCHead, error)
	DataDirFreeSpace() (int64, error)
}

LifecycleStorageEngine is the storage contract required by the lifecycle manager.

type MVCCLifecycleManager 

type MVCCLifecycleManager struct {
	// contains filtered or unexported fields
}

MVCCLifecycleManager coordinates MVCC pruning, pressure handling, and reader tracking.

func NewMVCCLifecycleManager 

func NewMVCCLifecycleManager(config LifecycleConfig, engine LifecycleStorageEngine) *MVCCLifecycleManager

NewMVCCLifecycleManager creates a lifecycle manager.

func (*MVCCLifecycleManager) AcquireSnapshotReader 

func (m *MVCCLifecycleManager) AcquireSnapshotReader(info storage.SnapshotReaderInfo) (func(), error)

AcquireSnapshotReader registers a reader and applies pressure-based rejection.

func (*MVCCLifecycleManager) EvaluateSnapshotReader 

func (m *MVCCLifecycleManager) EvaluateSnapshotReader(info storage.SnapshotReaderInfo) (graceful bool, hard bool)

EvaluateSnapshotReader reports whether an active reader should be cancelled or expired.

func (*MVCCLifecycleManager) IsLifecycleEnabled 

func (m *MVCCLifecycleManager) IsLifecycleEnabled() bool

IsLifecycleEnabled reports whether lifecycle is enabled.

func (*MVCCLifecycleManager) IsLifecycleRunning 

func (m *MVCCLifecycleManager) IsLifecycleRunning() bool

IsLifecycleRunning reports whether lifecycle is running.

func (*MVCCLifecycleManager) LifecycleStatus 

func (m *MVCCLifecycleManager) LifecycleStatus() map[string]interface{}

LifecycleStatus returns status suitable for admin endpoints.

func (*MVCCLifecycleManager) PauseLifecycle 

func (m *MVCCLifecycleManager) PauseLifecycle()

PauseLifecycle pauses automatic lifecycle work.

func (*MVCCLifecycleManager) ReaderRegistry 

func (m *MVCCLifecycleManager) ReaderRegistry() storage.SnapshotReaderRegistry

ReaderRegistry returns the active reader registry.

func (*MVCCLifecycleManager) RegisterSnapshotReader 

func (m *MVCCLifecycleManager) RegisterSnapshotReader(info storage.SnapshotReaderInfo) func()

RegisterSnapshotReader registers a reader without admission checks.

func (*MVCCLifecycleManager) ResumeLifecycle 

func (m *MVCCLifecycleManager) ResumeLifecycle()

ResumeLifecycle resumes automatic lifecycle work.

func (*MVCCLifecycleManager) RunPruneNow 

func (m *MVCCLifecycleManager) RunPruneNow(ctx context.Context, opts storage.MVCCPruneOptions) (int64, error)

RunPruneNow runs an immediate lifecycle prune.

func (*MVCCLifecycleManager) SetLifecycleSchedule 

func (m *MVCCLifecycleManager) SetLifecycleSchedule(interval time.Duration) error

SetLifecycleSchedule updates automatic lifecycle cadence. Zero disables automatic runs.

func (*MVCCLifecycleManager) StartLifecycle 

func (m *MVCCLifecycleManager) StartLifecycle(ctx context.Context)

StartLifecycle starts the background lifecycle loop.

func (*MVCCLifecycleManager) Status 

func (m *MVCCLifecycleManager) Status() map[string]interface{}

Status returns lifecycle state for diagnostics.

func (*MVCCLifecycleManager) StopLifecycle 

func (m *MVCCLifecycleManager) StopLifecycle()

StopLifecycle stops the lifecycle loop.

func (*MVCCLifecycleManager) TopLifecycleDebtKeys 

func (m *MVCCLifecycleManager) TopLifecycleDebtKeys(limit int) []storage.MVCCLifecycleDebtKey

TopLifecycleDebtKeys returns the highest-debt logical keys from the latest evaluated lifecycle plan.

func (*MVCCLifecycleManager) TriggerPruneNow 

func (m *MVCCLifecycleManager) TriggerPruneNow(ctx context.Context) error

TriggerPruneNow runs a prune cycle immediately.

type NamespaceBudget 

type NamespaceBudget struct {
	MaxBytesPerCycle int64
	MinSliceFraction float64
}

NamespaceBudget bounds lifecycle work for a namespace within one cycle.

type NamespaceDebtSummary 

type NamespaceDebtSummary struct {
	DebtBytes     int64
	DebtKeys      int64
	PrunableBytes int64
}

type NamespaceMetrics 

type NamespaceMetrics struct {
	CompactionDebtBytes atomic.Int64
	CompactionDebtKeys  atomic.Int64
	PrunableBytesTotal  atomic.Int64
	PrunedBytesTotal    atomic.Int64
}

NamespaceMetrics contains per-namespace lifecycle counters.

type PressureConfig 

type PressureConfig struct {
	HighEnterBytes      int64
	HighExitBytes       int64
	CriticalEnterBytes  int64
	CriticalExitBytes   int64
	PressureEnterWindow time.Duration
	PressureExitWindow  time.Duration
}

PressureConfig contains thresholds and debounce windows.

type PressureController 

type PressureController struct {
	// contains filtered or unexported fields
}

PressureController manages lifecycle pressure bands with hysteresis.

func NewPressureController 

func NewPressureController(config PressureConfig, pinnedBytes func() int64, freeSpace func() int64) *PressureController

NewPressureController creates a pressure controller.

func (*PressureController) CurrentBand 

func (p *PressureController) CurrentBand() storage.PressureBand

CurrentBand returns the current pressure band.

func (*PressureController) ShouldExpireReader 

func (p *PressureController) ShouldExpireReader(reader storage.SnapshotReaderInfo, maxLifetime time.Duration) (graceful bool, hard bool)

ShouldExpireReader decides whether a reader should be expired.

func (*PressureController) ShouldRejectLongSnapshot 

func (p *PressureController) ShouldRejectLongSnapshot(snapshotAge time.Duration, maxLifetime time.Duration) bool

ShouldRejectLongSnapshot decides whether a snapshot should be rejected under pressure.

func (*PressureController) Update 

func (p *PressureController) Update() storage.PressureBand

Update recalculates the current band using hysteresis.

type PriorityScheduler 

type PriorityScheduler struct {
	// contains filtered or unexported fields
}

PriorityScheduler ranks prune plan entries and enforces namespace budgets.

func NewPriorityScheduler 

func NewPriorityScheduler(config LifecycleConfig) *PriorityScheduler

NewPriorityScheduler creates a scheduler.

func (*PriorityScheduler) RecordProcessed 

func (s *PriorityScheduler) RecordProcessed(key string)

RecordProcessed resets skip accounting for a key.

func (*PriorityScheduler) RecordSkipped 

func (s *PriorityScheduler) RecordSkipped(key string)

RecordSkipped increments skip accounting for a key.

func (*PriorityScheduler) Schedule 

func (s *PriorityScheduler) Schedule(entries []PrunePlanEntry) []PrunePlanEntry

Schedule orders entries by debt-reduction-per-cost and applies namespace budgets.

func (*PriorityScheduler) ScheduleEmergency 

func (s *PriorityScheduler) ScheduleEmergency(entries []PrunePlanEntry) []PrunePlanEntry

ScheduleEmergency prioritizes the highest debt-yield keys first during emergency mode.

type PruneApplier 

type PruneApplier struct {
	// contains filtered or unexported fields
}

PruneApplier executes a prune plan with fence validation.

func NewPruneApplier 

func NewPruneApplier(config LifecycleConfig, metrics *LifecycleMetrics) *PruneApplier

NewPruneApplier creates an applier.

func (*PruneApplier) Apply 

func (p *PruneApplier) Apply(ctx context.Context, engine LifecycleStorageEngine, plan *PrunePlan) ApplyResult

Apply executes a prune plan.

type PrunePlan 

type PrunePlan struct {
	CreatedAt   time.Time
	KeysScanned int
	Entries     []PrunePlanEntry
}

PrunePlan describes an immutable lifecycle prune run.

type PrunePlanEntry 

type PrunePlanEntry struct {
	CreatedAt        time.Time
	LogicalKey       []byte
	HeadVersion      storage.MVCCVersion
	FloorVersion     storage.MVCCVersion
	NewFloorVersion  storage.MVCCVersion
	VersionsToDelete []storage.MVCCVersion
	DebtBytes        int64
	TombstoneDepth   int
}

PrunePlanEntry describes one logical key's prune work.

type PrunePlanner 

type PrunePlanner struct {
	// contains filtered or unexported fields
}

PrunePlanner builds immutable plans from MVCC heads and version chains.

func NewPrunePlanner 

func NewPrunePlanner(config LifecycleConfig) *PrunePlanner

NewPrunePlanner creates a planner.

func (*PrunePlanner) Plan 

func (p *PrunePlanner) Plan(ctx context.Context, engine LifecycleStorageEngine, safeFloorForNamespace func(namespace string) storage.MVCCVersion) (*PrunePlan, error)

Plan scans MVCC heads and computes per-key prune work.

safeFloorForNamespace resolves the prune-safe floor version for a given namespace. With per-database MVCC counters the global oldest-reader version is no longer comparable across namespaces; the planner must resolve a namespace-specific floor for each head it visits. A nil callback is treated as "no active readers anywhere" — every namespace resolves to maxVersion(), which lets the TTL/MaxVersions bounds drive pruning alone.

type ReaderRegistry 

type ReaderRegistry struct {
	// contains filtered or unexported fields
}

ReaderRegistry tracks active MVCC snapshot readers.

func NewReaderRegistry 

func NewReaderRegistry() *ReaderRegistry

NewReaderRegistry creates an empty reader registry.

func (*ReaderRegistry) ActiveCount 

func (r *ReaderRegistry) ActiveCount() int64

ActiveCount reports the number of active readers.

func (*ReaderRegistry) OldestReaderAge 

func (r *ReaderRegistry) OldestReaderAge() time.Duration

OldestReaderAge returns the maximum age of active readers.

func (*ReaderRegistry) OldestReaderVersion 

func (r *ReaderRegistry) OldestReaderVersion() (storage.MVCCVersion, bool)

OldestReaderVersion returns the smallest active snapshot version across all namespaces. Used for global metrics; for prune-floor decisions, prefer OldestReaderVersionByNamespace because version sequences are per-database and not comparable across namespaces.

func (*ReaderRegistry) OldestReaderVersionsByNamespace added in v1.1.1 

func (r *ReaderRegistry) OldestReaderVersionsByNamespace() map[string]storage.MVCCVersion

OldestReaderVersionsByNamespace returns the smallest active snapshot version per namespace. A namespace appears in the result only if it has at least one registered reader; callers should treat absence as "no active reader in this namespace" (effectively no floor).

Per-database MVCC counters mean a reader's CommitSequence in namespace A has no ordering relationship to a head's CommitSequence in namespace B — so the prune planner must use this map to compute a per-namespace safe floor, not the global oldest reader.

func (*ReaderRegistry) ReadersOlderThan 

func (r *ReaderRegistry) ReadersOlderThan(age time.Duration) []storage.SnapshotReaderInfo

ReadersOlderThan returns readers older than the supplied age.

func (*ReaderRegistry) Register 

func (r *ReaderRegistry) Register(info storage.SnapshotReaderInfo) (string, func())

Register adds a reader and returns its ID and deregistration callback.

func (*ReaderRegistry) Snapshot 

func (r *ReaderRegistry) Snapshot() []storage.SnapshotReaderInfo

Snapshot returns a copy of active reader metadata.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.