preempt

Documentation

Overview

Package preempt is the importable form of charly's RESOURCE-ARBITER plugin (cutover C9). It serves TWO capabilities:

• verb:arbiter — the exclusive/shared resource arbiter (the 1225-LOC logic moved OUT of charly core: acquire/release, stop+restore holders, the crash-safe lease ledger, GPU poisoning, the vfio<->nvidia mode arbitration). COMPILED-IN + dispatched IN-PROC by the in-core proxy (charly/preempt.go newResourceArbiter → resolve(verb:arbiter)+Invoke); the arbiter reaches its host dependencies over TWO generic reverse legs (arbiter.go): the VM/ pod lifecycle + GPU driver flip via sdk.Executor.InvokeProvider (FLOOR-SLIM-proper Unit-8, holder_dispatch.go), and its project deploy tree + resources via sdk.Executor.HostBuild("resolved-project") (K1-unblock wave 1, retiring the former bespoke arbiter reverse-RPC channel entirely).
• command:preempt — the operator `charly preempt status`/`restore` CLI. It OWNS the CLI grammar + the lease-table formatting and reaches its OWN peer capability verb:arbiter DIRECTLY via InvokeProvider over the reverse channel (no hidden `__preempt-*` forward, no in-core proxy hop — command:preempt → InvokeProvider → verb:arbiter). COMPILED-IN → dispatched in-proc via Invoke(OpRun); out-of-process CliMain errors (the reverse channel is unavailable there).

PLACEMENT — COMPILED-IN (listed in the embedded charly/charly.yml compiled_plugins:). The arbiter is on the deploy/vm/check hot paths + needs the local lease ledger + config, so in-proc is the right placement (like plugin-gpu). The reverse channel is in-proc (no gRPC broker) — the SAME dispatchBuild pattern.

Index

• func CliMain(args []string) int
• func NewMeta() pb.PluginMetaServer
• func NewProvider() pb.ProviderServer
• type ResourceArbiter
  • func (a *ResourceArbiter) AcquireExclusive(claimant string, tokens []string, claimAddr spec.HolderAddr, transient bool) (bool, error)
  • func (a *ResourceArbiter) AcquireShared(claimant string, tokens []string, claimAddr spec.HolderAddr, transient bool) (bool, error)
  • func (a *ResourceArbiter) ReleaseClaimant(claimant string, success bool) error
  • func (a *ResourceArbiter) Status() (*spec.PreemptLedger, []string, error)

Functions

func CliMain

func CliMain(args []string) int

CliMain is the OUT-OF-PROCESS command-dispatch entry (only reached when preempt is NOT compiled in). preempt reaches verb:arbiter over the reverse channel, unavailable out-of-process, so runPreemptCLI (with a nil executor) errors; the canonical placement is compiled-in (Invoke), where the reverse channel is threaded.

func NewMeta

func NewMeta() pb.PluginMetaServer

NewMeta advertises verb:arbiter (dispatched host-side via the in-core proxy, no authored plugin_input → no InputDef) + command:preempt (pass-through CLI args → no InputDef), plus the self-contained #PreemptPlugin schema (via sdk.NewMeta → BuildCapabilities) that satisfies the non-empty-schema load gate.

func NewProvider

func NewProvider() pb.ProviderServer

NewProvider returns the arbiter+command provider for in-proc registration or out-of-proc serving.

Types

type ResourceArbiter

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

ResourceArbiter coordinates exclusive host-resource access. The seams are injected so unit tests fake holder discovery + lifecycle without a live host; newArbiter wires them to the generic reverse-channel legs (HostBuild for gather/resources, InvokeProvider for the rest).

func (*ResourceArbiter) AcquireExclusive

func (a *ResourceArbiter) AcquireExclusive(claimant string, tokens []string, claimAddr spec.HolderAddr, transient bool) (bool, error)

AcquireExclusive gives a claimant SOLE use of its tokens: it stops every running preemptible holder AND every running SHARED-claim pod of them, flips each gpu-backed token to vfio, and persists a crash-safe lease. Returns active=true when a lease is held. tokens/claimAddr are pre-computed host-side by the in-core shim.

func (*ResourceArbiter) AcquireShared

func (a *ResourceArbiter) AcquireShared(claimant string, tokens []string, claimAddr spec.HolderAddr, transient bool) (bool, error)

AcquireShared brings up a SHARED (refcounted) claim. The FIRST shared claim flips the token's gpu-backed resource to nvidia (+ regenerate CDI) and preempts any running preemptible holder; subsequent claims just refcount. Refused only when an EXCLUSIVE claim already holds the token.

func (*ResourceArbiter) ReleaseClaimant

func (a *ResourceArbiter) ReleaseClaimant(claimant string, success bool) error

ReleaseClaimant restores the holders a claimant's lease stopped and removes the lease.

func (*ResourceArbiter) Status

func (a *ResourceArbiter) Status() (*spec.PreemptLedger, []string, error)

Status returns the current ledger plus the stranded-claimant names.