reservation

Documentation

Overview

Integration: The daemon holds the Ledger. Placement consults it for allocatable headroom. Execution creates/releases entries via the Ledger API.

Index

• func Path() string
• type ClusterSummary
• type Entry
  • func (e Entry) IsExpired(now time.Time) bool
  • func (e Entry) IsStale(now time.Time, window time.Duration) bool
• type Ledger
  • func NewLedger(limits Limits, logger *slog.Logger) *Ledger
  • func (l *Ledger) AllocatableRAM(node string) int64
  • func (l *Ledger) Entries() []Entry
  • func (l *Ledger) EntriesForNode(node string) []Entry
  • func (l *Ledger) Heartbeat(id string) error
  • func (l *Ledger) Load() error
  • func (l *Ledger) Metrics() Metrics
  • func (l *Ledger) NodeSummaryFor(node string) NodeSummary
  • func (l *Ledger) Reclaim() int
  • func (l *Ledger) Reconcile() int
  • func (l *Ledger) Release(id string) error
  • func (l *Ledger) Reserve(req Entry) (*Entry, error)
  • func (l *Ledger) Save() error
  • func (l *Ledger) SetNodeCapacity(node string, totalRAMMB int64)
  • func (l *Ledger) Summary() ClusterSummary
• type Limits
  • func DefaultLimits() Limits
• type Metrics
• type NodeSummary

Functions

func Path

func Path() string

Path returns the path to the ledger persistence file.

Types

type ClusterSummary

type ClusterSummary struct {
	Nodes           []NodeSummary `json:"nodes"`
	TotalReservedMB int64         `json:"total_reserved_mb"`
	TotalVRAMMB     int64         `json:"total_vram_mb"`
	ActiveEntries   int           `json:"active_entries"`
	StaleEntries    int           `json:"stale_entries"`
}

ClusterSummary aggregates reservation state across all nodes.

type Entry

type Entry struct {
	ID            string                 `json:"id"`
	Node          string                 `json:"node"`
	OwnerExecID   string                 `json:"owner_exec_id"`
	OwnerSurface  string                 `json:"owner_surface"`
	OwnerPID      int                    `json:"owner_pid,omitempty"`
	OwnerOrigin   models.ExecutionOrigin `json:"owner_origin,omitempty"`
	RAMMB         int64                  `json:"ram_mb"`
	VRAMMB        int64                  `json:"vram_mb,omitempty"`
	CreatedAt     time.Time              `json:"created_at"`
	LastHeartbeat time.Time              `json:"last_heartbeat"`
	ExpiresAt     time.Time              `json:"expires_at,omitempty"` // 0 = no hard expiry
	Description   string                 `json:"description,omitempty"`
}

Entry represents a single reservation on a node.

func (Entry) IsExpired

func (e Entry) IsExpired(now time.Time) bool

IsExpired returns true if the entry has a hard expiry that has passed.

func (Entry) IsStale

func (e Entry) IsStale(now time.Time, window time.Duration) bool

IsStale returns true if the entry has missed its heartbeat window.

type Ledger

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

Ledger is the central reservation accounting system.

func NewLedger

func NewLedger(limits Limits, logger *slog.Logger) *Ledger

NewLedger creates a reservation ledger.

func (*Ledger) AllocatableRAM

func (l *Ledger) AllocatableRAM(node string) int64

AllocatableRAM returns the allocatable RAM on a node after subtracting current reservations and system reserve.

func (*Ledger) Entries

func (l *Ledger) Entries() []Entry

Entries returns all current reservation entries.

func (*Ledger) EntriesForNode

func (l *Ledger) EntriesForNode(node string) []Entry

EntriesForNode returns reservations on a specific node.

func (*Ledger) Heartbeat

func (l *Ledger) Heartbeat(id string) error

Heartbeat updates the liveness timestamp for a reservation.

func (*Ledger) Load

func (l *Ledger) Load() error

Load reads the ledger from disk, replacing current entries.

func (*Ledger) Metrics

func (l *Ledger) Metrics() Metrics

func (*Ledger) NodeSummaryFor

func (l *Ledger) NodeSummaryFor(node string) NodeSummary

NodeSummaryFor returns the reservation summary for a specific node.

func (*Ledger) Reclaim

func (l *Ledger) Reclaim() int

Reclaim removes all stale and expired reservations. Returns count reclaimed. This is the primary orphan sweeper for the ledger.

func (*Ledger) Reconcile

func (l *Ledger) Reconcile() int

Reconcile is a semantic alias for Reclaim used during startup or recovery to emphasize the reconciliation pass.

func (*Ledger) Release

func (l *Ledger) Release(id string) error

Release removes a reservation by ID.

func (*Ledger) Reserve

func (l *Ledger) Reserve(req Entry) (*Entry, error)

Reserve attempts to create a reservation. Returns the Entry on success. Fails if node capacity is unknown or if it would violate overcommit limits or per-node caps.

func (*Ledger) Save

func (l *Ledger) Save() error

Save writes the ledger to disk.

func (*Ledger) SetNodeCapacity

func (l *Ledger) SetNodeCapacity(node string, totalRAMMB int64)

SetNodeCapacity updates the total RAM capacity for a node. Called when snapshots are refreshed.

func (*Ledger) Summary

func (l *Ledger) Summary() ClusterSummary

Summary returns the cluster-wide reservation summary.

type Limits

type Limits struct {
	// MaxOvercommitRatio is the max ratio of reserved/total RAM per node.
	// 1.0 = no overcommit. 1.5 = allow 50% overcommit. 0 = unlimited.
	MaxOvercommitRatio float64 `yaml:"max_overcommit_ratio" json:"max_overcommit_ratio"`
	// SystemReserveMB is RAM held back from allocation (default 1024).
	SystemReserveMB int64 `yaml:"system_reserve_mb" json:"system_reserve_mb"`
	// HeartbeatStaleWindow is how long since last heartbeat before stale.
	HeartbeatStaleWindow time.Duration `yaml:"heartbeat_stale_window" json:"heartbeat_stale_window"`
	// MaxEntriesPerNode caps concurrent reservations per node.
	MaxEntriesPerNode int `yaml:"max_entries_per_node" json:"max_entries_per_node"`
}

Limits controls over-commitment policy.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits returns conservative defaults.

type Metrics

type Metrics struct {
	TotalReservedMB  int64 `json:"total_reserved_mb"`
	TotalReleasedMB  int64 `json:"total_released_mb"`
	TotalReclaimedMB int64 `json:"total_reclaimed_mb"`
	ReserveFailures  int64 `json:"reserve_failures"`
	ActiveEntries    int   `json:"active_entries"`
}

Metrics returns ledger-level metrics.

type NodeSummary

type NodeSummary struct {
	Node           string  `json:"node"`
	TotalRAMMB     int64   `json:"total_ram_mb"`
	ReservedRAMMB  int64   `json:"reserved_ram_mb"`
	ReservedVRAMMB int64   `json:"reserved_vram_mb"`
	ActiveEntries  int     `json:"active_entries"`
	StaleEntries   int     `json:"stale_entries"`
	UtilizationPct float64 `json:"utilization_pct"`
}

NodeSummary aggregates reservation state for a single node.