Enum AcquireError 

pub enum AcquireError {
    AtCapacity {
        capacity: usize,
    },
    OutOfReservation {
        requested: usize,
        reserved: usize,
        budget: usize,
    },
    SpawnFailed(Error),
    ShuttingDown,
}

Why WorkerPool::acquire refused.

The defect this closes

acquire refuses at two gates that mean opposite things to whoever has to act on the refusal:

• AtCapacity — this process said no. Every set the pool may create is already leased. The remedy is to raise the bound (or to accept the bound as the connection limit it is); the target is fine.
• OutOfReservation — this process said no on behalf of the target: admitting would reserve more thread memory than the process is allowed to hold. The remedy is RAM plus a raised POOL_RESERVATION_ENV, and the target is still healthy — which is the whole point of refusing here rather than one connection later.
• SpawnFailed — the target said no. The OS refused to create the set’s threads. The remedy is memory, and the pool’s own bound is irrelevant because it was never reached.

Both used to be an io::Error, and both landed on io::ErrorKind::WouldBlock — the capacity arm by construction, the spawn arm because a failed Builder::spawn is EAGAIN and std decodes EAGAIN as WouldBlock. So the one discriminator a consumer had was the message prose, and every consumer that branched on kind() silently answered the wrong question. Both server drivers did: the CA server reported both as one status on the wire — measured on VxWorks 7, where both gates were reached on one image with available=48 on each (doc/vxworks-ca-refusal-fidelity.md §6) — and the PVA server’s kind() == WouldBlock arm reports an out-of-threads target as max_connections reached, naming a bound that never fired. That second one is by construction, not measured: the blocking PVA server has not been driven to its wall on this target.

Naming the gate in the type is what makes that class of mistake unwritable: a consumer that wants “is this the connection limit” must now say so, and gets an answer that cannot be an EAGAIN in disguise.

The From conversion to io::Error keeps each variant’s historical ErrorKind for callers that only propagate, and carries self as the error’s payload so the gate survives the conversion and stays recoverable with downcast_ref.

Variants

AtCapacity

Every set the pool may ever create is leased out. capacity is the bound that was reached — the number to report and the number to raise.

Fields

capacity: usize

The pool’s declared capacity, in sets.

OutOfReservation

Admitting would take the process past its thread-memory budget. Nothing was reserved and no thread was created.

Fields

requested: usize

What this set would have reserved, in bytes.

reserved: usize

Already reserved by every pool in the process, in bytes.

budget: usize

The process budget, in bytes — the number POOL_RESERVATION_ENV raises.

SpawnFailed(Error)

The OS refused to create the set’s threads. The pool was below its capacity and created is left exactly as it was found.

ShuttingDown

The pool is shutting down and will not lease again.

Trait Implementations

impl Debug for AcquireError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for AcquireError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for AcquireError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<AcquireError> for Error

fn from(cause: AcquireError) -> Error

Converts to this type from the input type.