Crate orbit_pool 

Fleet-wide resource leases, reservations and creation claims over Orbit shared memory.

A resource is something one process owns and others may use through it: an upstream connection, a worker, a slot in anything with a limit. The owner Pool::registers it under a Key (the caller’s digest of “what this is usable for”) with a capacity: one for an exclusive thing, more for one that admits several users at once. Any process in the fleet then reads the Pool::candidates for a key, picks one by its own policy, and Pool::reserves capacity on it: one compare-and- swap that either hands back a Lease or says Error::Busy. The opaque object never moves; a lease is the right to ask its owner to use it. The owner Pool::accepts the lease, does the work, and its Execution guard gives the unit back when the work is over. A caller that gives up frees nothing: only the owner knows when the resource is idle again, so a reservation the owner never saw is aged out by the owner’s Pool::reconcile, never by a caller’s timeout.

A per-key creation budget keeps a fleet that finds a key empty from creating everything at once: Pool::claim_create counts live and in-progress resources together. Waiters park on the key until capacity comes back, in a thread or in a task.

The pool decides nothing and carries nothing: which candidate wins is the caller’s policy, and the bytes of a remote use travel over orbit-stream. Standalone it lives in process memory; in a fleet, in the shared segment a PoolSpec names — kind POOL_KIND by default, and one fleet may hold several independent pools.

Structs

Candidate

One resource usable for a key, as the fleet sees it right now. Fields are expected to be added as the table learns to report more, so this is read rather than constructed from outside.

CreationPermit

One unit of a key’s creation budget, held while a resource is being made. Dropping it gives the unit back, whether or not a resource was registered meanwhile.

Execution

The owner’s guard over one accepted lease. Dropping it, or Execution::complete, gives the unit back and wakes the key. It is the only way capacity returns: a caller that vanished mid-way changes nothing until the owner’s work has actually ended.

Incarnation

Which life of a process owns a resource or holds a claim. Supplied by the embedder, one value per process life; see orbit-stream for the same idea.

Key

What a resource is usable for. The pool never hashes: the caller brings a 128-bit digest of its real key (an origin plus everything that forbids reuse across contexts), so two resources with equal keys are interchangeable by the caller’s own definition.

Lease

Reserved capacity on one resource. Plain data: it crosses processes as numbers, and the owner validates it against the slot before use.

Limits

Caller-supplied bounds for one acquisition.

LocalFirst

The starting policy: a local resource with room, else a remote one with room (least loaded first), else create within the budget, else wait. No number from any benchmark is built in; whether remote reuse beats creation is a measurement the embedder makes and expresses in its own policy.

LocalOnly

Never leaves this process: local reuse, else create, else wait. What a standalone runtime or a LocalOnly profile uses; remote candidates are invisible to it even when they exist.

Pool

The fleet’s pool table. Cheap to clone; every clone in a process is the same table, driver and wakers.

PoolSpec

Which segment a Pool uses, and how big it is.

Readiness

The consumer’s end: put it in a poll set, drain it, re-read your state.

ResourceId

The address of one resource: a NetId64 whose node is the owner’s lane and whose counter is the slot and its generation.

Enums

Decision

What the policy wants done next.

Error

Additions are expected: a cause discovered later lands here rather than in a new major version, so a caller matches what it handles and leaves the rest to a catch-all.

Plan

What Pool::acquire committed to. Reuse variants hold a reservation already taken; Create holds creation budget already claimed. Neither is advisory.

Reason

Why a policy would not serve the request, for logs and metrics.

State

Where a resource stands, as read from the table: a snapshot, never a reservation.

Constants

PENDING_RESERVATIONS

Unaccepted reservations one resource can hold at once. Part of the slot ABI, not a tunable: an owner that is this far behind is the problem, not the table.

POOL_KEY_CAPACITY

Distinct keys one fleet epoch can name at once, in the default spec.

POOL_KIND

Reserved Orbit SHM kind for the default pool segment. Another pool names its own through a PoolSpec.

POOL_RESOURCE_LANE_CAPACITY

Resources one fleet node can have registered at once, in the default spec.

Traits

Policy

Functions

segment_size

Bytes the default spec’s segment needs for fleet_capacity lanes.

segment_size_for

Bytes spec’s segment needs for fleet_capacity lanes.

Type Aliases

Result