| Safe Haskell | None |
|---|---|
| Language | GHC2021 |
Ecluse.Rts
Description
Resolving and applying the process's runtime posture: the capability count, the allocation area and the heap ceiling.
The RTS sizes itself from the machine, not the pod. Bare -N claims a capability per visible
processor, a cgroup CPU quota does not shrink that count, and the heap is unbounded unless -M
says so, leaving the kernel OOM killer as the only backstop. Neither -A nor -M has an in-process
setter, so applying one re-executes this binary in place once, guarded by reexecMarker. Sizes are
bytes throughout.
Synopsis
- applyRuntimePosture :: (Text -> IO ()) -> (Text -> IO ()) -> RuntimeOverrides -> IO EffectiveRuntimePlan
- data RtsPosture = RtsPosture {}
- data CgroupLimits = CgroupLimits {}
- data RuntimeOverrides = RuntimeOverrides {
- roCores :: Maybe Int
- roCoresCeiling :: Maybe Int
- roMaxHeapBytes :: Maybe Int
- data Provenance
- data RuntimePlan = RuntimePlan {
- planCapabilities :: (Int, Provenance)
- planAllocAreaBytes :: (Int, Provenance)
- planMaxHeapBytes :: (Maybe Int, Provenance)
- provenanceClause :: Provenance -> Text
- resolveRuntimePlan :: RuntimeOverrides -> CgroupLimits -> RtsPosture -> RuntimePlan
- currentRtsPosture :: IO RtsPosture
- readCgroupLimits :: IO CgroupLimits
- deriveMaxHeapBytes :: Int -> Int -> Int
- deriveAllocAreaBytes :: Int -> Int -> Int
- requiredRtsFlags :: RtsPosture -> RuntimePlan -> [Text]
- data EffectiveAxis a = EffectiveAxis {
- axDesired :: a
- axObserved :: a
- axProvenance :: Provenance
- data EffectiveRuntimePlan = EffectiveRuntimePlan {}
- axEnforced :: Eq a => EffectiveAxis a -> Bool
- reconcileRuntimePlan :: CgroupLimits -> RuntimePlan -> RtsPosture -> EffectiveRuntimePlan
- appliedRuntimePlan :: CgroupLimits -> RuntimePlan -> RtsPosture -> EffectiveRuntimePlan
- effectiveCapabilities :: EffectiveRuntimePlan -> (Int, Provenance)
- effectiveHeapCeiling :: EffectiveRuntimePlan -> (Maybe Int, Provenance)
- renderEffectivePosture :: EffectiveRuntimePlan -> [Text]
- renderPostureWarnings :: EffectiveRuntimePlan -> [Text]
- parseCpuMax :: Text -> Maybe Double
- parseMemoryMax :: Text -> Maybe Int
- readIfExists :: FilePath -> IO (Maybe Text)
- parseInactiveFile :: Text -> Maybe Int
- usePermille :: Int -> Maybe Int -> Int -> Int
- cgroupMemoryUse :: IO (IO (Maybe Int))
Applying the resolved posture at boot
applyRuntimePosture :: (Text -> IO ()) -> (Text -> IO ()) -> RuntimeOverrides -> IO EffectiveRuntimePlan Source #
Resolve the runtime plan and apply it, first thing at boot. It never aborts the boot, and the plan it returns is the effective one, so downstream sizing computes from what the RTS runs with.
The pure resolution core
data RtsPosture Source #
The RTS posture the process is actually running with, read at boot by currentRtsPosture.
Constructors
| RtsPosture | |
Fields
| |
Instances
| Show RtsPosture Source # | |
Defined in Ecluse.Rts Methods showsPrec :: Int -> RtsPosture -> ShowS # show :: RtsPosture -> String # showList :: [RtsPosture] -> ShowS # | |
| Eq RtsPosture Source # | |
Defined in Ecluse.Rts | |
data CgroupLimits Source #
What the cgroup (v2) grants this process: the CPU quota in cores and the memory ceiling in
bytes. Nothing per axis when the file is absent or carries the unlimited max sentinel.
Constructors
| CgroupLimits | |
Fields | |
Instances
| Show CgroupLimits Source # | |
Defined in Ecluse.Rts Methods showsPrec :: Int -> CgroupLimits -> ShowS # show :: CgroupLimits -> String # showList :: [CgroupLimits] -> ShowS # | |
| Eq CgroupLimits Source # | |
Defined in Ecluse.Rts | |
data RuntimeOverrides Source #
The runtime configuration the resolution reads. Each unset field falls to the next rung,
and roCoresCeiling bounds the last rung alone.
Constructors
| RuntimeOverrides | |
Fields
| |
Instances
| Show RuntimeOverrides Source # | |
Defined in Ecluse.Rts Methods showsPrec :: Int -> RuntimeOverrides -> ShowS # show :: RuntimeOverrides -> String # showList :: [RuntimeOverrides] -> ShowS # | |
| Eq RuntimeOverrides Source # | |
Defined in Ecluse.Rts Methods (==) :: RuntimeOverrides -> RuntimeOverrides -> Bool # (/=) :: RuntimeOverrides -> RuntimeOverrides -> Bool # | |
data Provenance Source #
Where a resolved value came from, for the boot log's provenance clause.
Constructors
| FromConfig | Explicit Écluse configuration ( |
| FromCgroup | Derived from the cgroup CPU quota, or from |
| FromCgroupMemory | Bounded by what the cgroup memory limit can feed, for want of a CPU quota. |
| FromCoresCeiling | Capped at |
| FromHeapCeiling | Fitted to a heap ceiling from config, or from |
| FromRts | Left as the RTS resolved it (baked defaults plus any operator |
Instances
| Show Provenance Source # | |
Defined in Ecluse.Rts Methods showsPrec :: Int -> Provenance -> ShowS # show :: Provenance -> String # showList :: [Provenance] -> ShowS # | |
| Eq Provenance Source # | |
Defined in Ecluse.Rts | |
data RuntimePlan Source #
The resolved runtime posture: the capability count, allocation area and heap ceiling to run
with, each with its provenance. A FromRts entry means leave the live posture alone.
Constructors
| RuntimePlan | |
Fields
| |
Instances
| Show RuntimePlan Source # | |
Defined in Ecluse.Rts Methods showsPrec :: Int -> RuntimePlan -> ShowS # show :: RuntimePlan -> String # showList :: [RuntimePlan] -> ShowS # | |
| Eq RuntimePlan Source # | |
Defined in Ecluse.Rts | |
provenanceClause :: Provenance -> Text Source #
The provenance as a bare clause, for consumers composing their own log lines.
resolveRuntimePlan :: RuntimeOverrides -> CgroupLimits -> RtsPosture -> RuntimePlan Source #
Resolve the runtime plan: capabilities down the four-rung ladder, the heap ceiling from
maxHeapBytes, else the cgroup limit, else GHCRTS, and the allocation area to fit either bound.
deriveMaxHeapBytes :: Int -> Int -> Int Source #
The heap ceiling derived from a cgroup memory limit, floored at half the limit. The nursery
counts inside -M (GHC 9.6 and later), so only an overshoot allowance and off-heap memory come off.
deriveAllocAreaBytes :: Int -> Int -> Int Source #
The per-capability allocation area for a memory limit: an eighth of the limit across the capabilities, in whole MiB from 4 to 64. A smaller nursery costs collector time, not a core.
requiredRtsFlags :: RtsPosture -> RuntimePlan -> [Text] Source #
The RTS flags the plan requires beyond the live posture, in GHCRTS syntax. A FromRts
entry never contributes a flag, because it is the live posture.
The effective plan (desired reconciled with observed)
data EffectiveAxis a Source #
One axis of the runtime posture after the boot applied the plan. An apply can fail, so
downstream sizings read effectiveCapabilities and effectiveHeapCeiling, never the desired plan.
Constructors
| EffectiveAxis | |
Fields
| |
Instances
| Show a => Show (EffectiveAxis a) Source # | |
Defined in Ecluse.Rts Methods showsPrec :: Int -> EffectiveAxis a -> ShowS # show :: EffectiveAxis a -> String # showList :: [EffectiveAxis a] -> ShowS # | |
| Eq a => Eq (EffectiveAxis a) Source # | |
Defined in Ecluse.Rts Methods (==) :: EffectiveAxis a -> EffectiveAxis a -> Bool # (/=) :: EffectiveAxis a -> EffectiveAxis a -> Bool # | |
data EffectiveRuntimePlan Source #
The runtime plan reconciled with the posture the RTS actually runs: each planned axis as a desired/observed pair, plus the observed-only datapoints downstream sizing needs.
Constructors
| EffectiveRuntimePlan | |
Fields
| |
Instances
| Show EffectiveRuntimePlan Source # | |
Defined in Ecluse.Rts Methods showsPrec :: Int -> EffectiveRuntimePlan -> ShowS # show :: EffectiveRuntimePlan -> String # showList :: [EffectiveRuntimePlan] -> ShowS # | |
| Eq EffectiveRuntimePlan Source # | |
Defined in Ecluse.Rts Methods (==) :: EffectiveRuntimePlan -> EffectiveRuntimePlan -> Bool # (/=) :: EffectiveRuntimePlan -> EffectiveRuntimePlan -> Bool # | |
axEnforced :: Eq a => EffectiveAxis a -> Bool Source #
Whether the live RTS backs an axis (desired and observed agree).
reconcileRuntimePlan :: CgroupLimits -> RuntimePlan -> RtsPosture -> EffectiveRuntimePlan Source #
Pair the desired plan with the posture the RTS reports, axis by axis.
appliedRuntimePlan :: CgroupLimits -> RuntimePlan -> RtsPosture -> EffectiveRuntimePlan Source #
The effective plan a successful application would produce, observed equal to desired.
check-config sizes from this because it applies nothing, so its own posture is not the boot's.
effectiveCapabilities :: EffectiveRuntimePlan -> (Int, Provenance) Source #
The live capability count: budgets must never exceed what the RTS actually runs with, so the
observed side is authoritative. An unenforced count degrades the provenance to FromRts.
effectiveHeapCeiling :: EffectiveRuntimePlan -> (Maybe Int, Provenance) Source #
The sizing ceiling: the tighter of desired and observed. An observed -M below the plan
binds, and an absent one leaves the desired ceiling standing on the cgroup limit's OOM backstop.
renderEffectivePosture :: EffectiveRuntimePlan -> [Text] Source #
The boot log's posture lines, one decision per line with its provenance. The allocation area
has no config key: the cgroup limit or an operator GHCRTS sets it.
renderPostureWarnings :: EffectiveRuntimePlan -> [Text] Source #
The boot log's posture warnings: an axis the RTS is not enforcing, and a capability count no entitlement backs.
Cgroup v2 parsing
readIfExists :: FilePath -> IO (Maybe Text) Source #
Read a file that may be absent, as off a cgroup-v2 host. Every other IO error propagates.
parseInactiveFile :: Text -> Maybe Int Source #
The inactive_file bytes in a cgroup-v2 memory.stat body: page cache the kernel reclaims first.
usePermille :: Int -> Maybe Int -> Int -> Int Source #
Memory in use less reclaimable page cache, in thousandths of the limit, from a cgroup's readings.