Struct Pool 

pub struct Pool { /* private fields */ }

A fixed set of worker threads that Exec tokens place work on.

Pool is the only way to make a pool. It wraps the scheduler privately: no scheduler type appears in any signature, there is no constructor from an external pool and no accessor returning one. The pool’s owner keeps the Pool and mints tokens from it with Exec::new.

A Pool is a unique owner: it is not Clone and no method returns a second handle. An engine that wants reserved, always-awake members moves the pool into a Team with into_team; the team owns the pool from then on (and gives it back with Team::into_pool). Sharing a pool between several callers stays outside this crate (for example behind an Arc held by the caller), where each call acquires its members with Exec::team or uses plain tokens.

Dropping a Pool (or the Team that owns it) ends its team members. What happens to the worker threads depends on how the pool was built:

• A pool with a thread_name, an on_start hook, a stack_size or a qos of its own has dedicated workers: the drop shuts them down and joins them, so when drop returns every worker thread has exited and its thread-local destructors (including state set up by the hook) have run.
• A pool with the default thread settings has shared workers: the drop waits until its members left, then keeps the idle workers in a process-wide cache, keyed by width. The next build of a default pool of the same width takes them instead of starting threads, and gives each worker the calling thread’s CPU set. A cached set of workers belongs to one pool at a time. The cache holds at most as many threads as the larger of the available parallelism and the widest pool built so far; the oldest entries beyond that are joined.

Without the parallel feature there are no workers and nothing is joined.

A pool dropped from one of its own workers cannot wait for itself: that drop signals shutdown and returns without joining, so the workers exit shortly after instead of before the return. Drop the pool from a plain thread when the guarantee matters.

Examples

use threadteam::Pool;

let pool = Pool::builder().threads(2).thread_name(|i| format!("w{i}")).build()?;
assert!(pool.width().get() <= 2);

Implementations

impl Pool

pub fn builder() -> PoolBuilder

Starts configuring a pool.

Examples

let pool = threadteam::Pool::builder().threads(1).build()?;
assert_eq!(pool.width().get(), 1);

pub fn width(&self) -> NonZero<usize>

Number of worker threads, the largest budget a token can have.

Without the parallel feature this is always 1.

Examples

let pool = threadteam::Pool::builder().threads(1).build()?;
assert_eq!(pool.width().get(), 1);

pub fn wait_policy(&self) -> WaitPolicy

The pool-wide default WaitPolicy of idle team members.

Examples

use std::time::Duration;

let pool = threadteam::Pool::builder()
    .threads(1)
    .idle_spin(Duration::from_millis(5))
    .build()?;
assert_eq!(pool.wait_policy().idle_spin(), Duration::from_millis(5));

pub fn release_idle(&self)

Asks idle team members to return their threads to Rayon now.

Members that are idle leave at once; members that are reserved leave when their reservation ends, so this never revokes a live TeamExec. The call does not wait for anything, so it is safe to make from inside a reservation. A team acquired later starts its members afresh.

Examples

let pool = threadteam::Pool::builder().threads(2).build()?;
pool.release_idle(); // nothing resident: no effect

pub fn dispatch_costs(&self) -> DispatchCosts

The DispatchCosts of this pool’s tokens.

Examples

use threadteam::{DispatchCosts, Pool};
let pool = Pool::builder().threads(1).build()?;
assert_eq!(pool.dispatch_costs(), DispatchCosts::host_default());

pub fn pin_participants(&self) -> bool

Whether the pool pins the members of a root team scope (see PoolBuilder::pin_participants); the leader is never pinned.

Examples

let pool = threadteam::Pool::builder().threads(1).build()?;
assert!(!pool.pin_participants()); // off by default

pub fn spin_polls(&self) -> u32

The spin budget of this pool’s team waits, in polls (PoolBuilder::spin_polls).

pub fn resident_members(&self) -> usize

Number of workers currently kept awake as team members, reserved or idle. Zero once idle members returned to Rayon. A diagnostic: the value can change at any moment.

Examples

let pool = threadteam::Pool::builder().threads(2).build()?;
assert_eq!(pool.resident_members(), 0);

impl Pool

pub fn into_team(self, width: usize) -> Result<Team, IntoTeamError>

Moves the pool into a Team that reserves width - 1 members for as long as it lives.

width counts the leader and is clamped to the pool width; zero is treated as one. Acquisition never waits for a running Rayon job (see Exec::team). Members park after the pool’s spin budget without work (PoolBuilder::spin_polls).

Errors

IntoTeamError when the members could not all be reserved; it gives the pool back with the Refused reason so the caller falls back to plain tokens.

Examples

let pool = threadteam::Pool::builder()
    .threads(3)
    .acquire_timeout(std::time::Duration::from_secs(10))
    .build()?;
let team = pool.into_team(3).expect("an idle pool");
assert_eq!(team.size().get(), team.pool().width().get().min(3));

pub fn into_team_with( self, width: usize, over: WaitOverride, ) -> Result<Team, IntoTeamError>

into_team with an override of the wait policy of the reservation. The reserved members’ waits for work use the pool’s spin budget, not idle_spin (docs/design/waiting.md); the override is kept for the policy the team reports.

Errors

As into_team.

Trait Implementations

impl Debug for Pool

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

Formats the value using the given formatter.

impl Drop for Pool

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

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

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.