pub struct Pool { /* private fields */ }Expand description
The fleet’s pool table. Cheap to clone; every clone in a process is the same table, driver and wakers.
Implementations§
Source§impl Pool
impl Pool
Sourcepub fn new(fleet: Arc<Fleet>, incarnation: Incarnation) -> Result<Self>
pub fn new(fleet: Arc<Fleet>, incarnation: Incarnation) -> Result<Self>
Open the fleet’s default pool table.
Sourcepub fn with_spec(
fleet: Arc<Fleet>,
incarnation: Incarnation,
spec: PoolSpec,
) -> Result<Self>
pub fn with_spec( fleet: Arc<Fleet>, incarnation: Incarnation, spec: PoolSpec, ) -> Result<Self>
Open the table spec names. Independent specs are independent
pools: separate segments, separate budgets, separate epochs, and a
reset_all on one leaves the others alone. A process may hold as
many as it has specs, but each under one incarnation.
Sourcepub fn readiness(&self) -> Result<Readiness>
pub fn readiness(&self) -> Result<Readiness>
A descriptor that becomes readable when a key this node
Pool::watches may have changed, for a runtime that parks on
descriptors rather than on wakers or on the key’s word.
Edge-triggered and coalescing: drain it, then re-try what you
wanted — claim_create, reserve, acquire. It composes, which
is the point: a worker waiting for its next request and for pool
capacity puts both descriptors in one poll set and gives that call
its deadline, instead of choosing which one to block on.
One per table; a second caller is refused rather than handed a descriptor whose signals the first would drain.
Sourcepub fn watch(&self, key: Key) -> Result<()>
pub fn watch(&self, key: Key) -> Result<()>
Ask to be signalled when key changes.
Interest is taken by the driver when it delivers, exactly as a
waker is, so this is re-armed before each wait — take the
Pool::version, try, watch, then wait, and a change between the
try and the wait is seen rather than missed.
pub fn node(&self) -> NodeId
pub fn incarnation(&self) -> Incarnation
pub fn epoch(&self) -> u64
Sourcepub fn register(&self, key: Key, capacity: u32) -> Result<ResourceId>
pub fn register(&self, key: Key, capacity: u32) -> Result<ResourceId>
Make a resource this process owns visible under key with
capacity concurrent leases (1 for an exclusive resource).
Sourcepub fn unregister(&self, id: ResourceId) -> Result<()>
pub fn unregister(&self, id: ResourceId) -> Result<()>
Take the resource away. Leases out on it become stale.
Sourcepub fn drain(&self, id: ResourceId) -> Result<()>
pub fn drain(&self, id: ResourceId) -> Result<()>
No new leases; the ones out finish at their own pace.
Sourcepub fn reconcile(
&self,
id: ResourceId,
active: u32,
grace: Duration,
) -> Result<()>
pub fn reconcile( &self, id: ResourceId, active: u32, grace: Duration, ) -> Result<()>
The owner’s truth: active becomes the table’s active count, and
every reservation older than grace that nobody brought to the
owner is aged out, so its unit returns and a late accept of it is
refused. grace bounds how long an abandoned reservation keeps a
unit; it says nothing about running work.
Sourcepub fn candidates(&self, key: Key) -> Vec<Candidate>
pub fn candidates(&self, key: Key) -> Vec<Candidate>
Every resource registered under key, in table order.
Sourcepub fn reserve(&self, id: ResourceId) -> Result<Lease>
pub fn reserve(&self, id: ResourceId) -> Result<Lease>
One unit of the resource’s capacity, or Error::Busy. One
compare-and-swap; a snapshot that showed room is not a lease.
Sourcepub fn accept(&self, lease: Lease) -> Result<Execution>
pub fn accept(&self, lease: Lease) -> Result<Execution>
The owner takes a lease a caller brought it: the unit moves from
reserved to active and the returned guard gives it back when the
work is over, however it ends. Only the owner can accept, and only
while the resource is live in the lease’s generation. A reservation
that never made it here is not the caller’s to undo; the owner’s
Pool::reconcile ages it out.
Sourcepub fn is_current(&self, lease: Lease) -> bool
pub fn is_current(&self, lease: Lease) -> bool
Whether lease is the current state of its resource: the resource
is live in that generation and the fence has not been passed by a
later lease’s release.
Sourcepub fn acquire(
&self,
key: Key,
limits: &Limits,
policy: &dyn Policy,
) -> Result<Plan>
pub fn acquire( &self, key: Key, limits: &Limits, policy: &dyn Policy, ) -> Result<Plan>
One decision for key: snapshot the candidates, ask policy, then
reserve or claim what it chose. A candidate that turns out busy is a
lost race, retried with a fresh snapshot up to limits.attempts
times; after that the answer is Plan::Wait. Nothing is executed
and nothing is transported here.
Sourcepub fn claim_create(&self, key: Key, max_live: u32) -> Result<CreationPermit>
pub fn claim_create(&self, key: Key, max_live: u32) -> Result<CreationPermit>
Claim one unit of the key’s creation budget: live resources plus
claims in progress stay under max_live. Drop the permit when the
resource is registered (or the attempt failed).
Sourcepub fn budget(&self, key: Key) -> (u32, u32)
pub fn budget(&self, key: Key) -> (u32, u32)
The key’s live and in-progress counts, for the caller’s growth decisions.
Sourcepub fn wait_capacity_timeout(
&self,
key: Key,
since: u32,
timeout: Duration,
) -> Result<Option<u32>>
pub fn wait_capacity_timeout( &self, key: Key, since: u32, timeout: Duration, ) -> Result<Option<u32>>
The same wait, bounded: None is the timeout and nothing else.
This is what a caller with a deadline of its own uses — an
admission window, a request that must answer busy rather than
queue forever. Take the version before the attempt, as with
Pool::wait_capacity, so a change between the two is seen
instead of waited for.
Sourcepub fn version(&self, key: Key) -> Result<u32>
pub fn version(&self, key: Key) -> Result<u32>
The key’s change count; what Pool::wait_capacity waits past.
Sourcepub fn wait_capacity(&self, key: Key, since: u32) -> Result<u32>
pub fn wait_capacity(&self, key: Key, since: u32) -> Result<u32>
Park the thread until the key has changed since since: a release,
an unregister, a closed resource, a dropped claim. Coalescing: any
number of changes wake once. Returns the count now.
Sourcepub fn poll_capacity(
&self,
key: Key,
since: u32,
cx: &mut Context<'_>,
) -> Poll<Result<u32>>
pub fn poll_capacity( &self, key: Key, since: u32, cx: &mut Context<'_>, ) -> Poll<Result<u32>>
Readiness for a task: Ready with the count now once the key has
changed since since; otherwise the waker is registered and
Pending comes back.
Sourcepub fn owners(&self) -> Vec<(NodeId, Incarnation)>
pub fn owners(&self) -> Vec<(NodeId, Incarnation)>
Every process generation that still owns a resource here.
For a supervisor that lost its record of who was running — its own
restart, with workers adopted rather than replaced — and has to
decide what to report dead. The table is the authority: a
(node, incarnation) in this list holds resources whose units are
still counted against their keys, whether or not that process
exists.
It says who is in the table, never who is alive; the caller
subtracts the generations it knows are running and reports the
rest. Creation claims are not represented here — they are counted
per node without a generation, and Pool::node_dead returns them
whichever incarnation it names.
Sourcepub fn node_dead(&self, node: NodeId, incarnation: Incarnation)
pub fn node_dead(&self, node: NodeId, incarnation: Incarnation)
A confirmed death, reported by whoever supervises processes: every
resource that incarnation of node owned is closed and the
creation claims it held are returned. Leases it held on others’
resources are those owners’ to reconcile.