Struct PoolBuilder 

pub struct PoolBuilder { /* private fields */ }

Configuration of a Pool.

Examples

use threadteam::Pool;

let pool = Pool::builder()
    .threads(2)
    .stack_size(8 << 20)
    .on_start(|_worker| { /* e.g. pin the thread */ })
    .build()?;
assert!(pool.width().get() >= 1);

Implementations

impl PoolBuilder

pub fn threads(self, n: usize) -> PoolBuilder

Number of worker threads. Defaults to the available parallelism.

Zero is rejected by build; the pool never falls back to an environment-dependent default.

Examples

use threadteam::{Error, Pool};

assert_eq!(Pool::builder().threads(0).build().unwrap_err(), Error::ZeroThreads);

pub fn thread_name(self, f: impl Fn(usize) -> String + 'static) -> PoolBuilder

Names the workers; the closure receives the worker index.

Examples

let pool = threadteam::Pool::builder()
    .threads(1)
    .thread_name(|i| format!("my-pool-{i}"))
    .build()?;

pub fn stack_size(self, bytes: usize) -> PoolBuilder

Worker stack size in bytes. Defaults to 16 MiB, sized for recursive LU.

Examples

let pool = threadteam::Pool::builder().threads(1).stack_size(4 << 20).build()?;

pub fn on_start(self, f: impl Fn(usize) + Send + Sync + 'static) -> PoolBuilder

Hook run on each worker when it starts, with the worker index.

Typical use is pinning the worker to a core. The hook is not called without the parallel feature, which starts no workers.

Examples

let pool = threadteam::Pool::builder().threads(1).on_start(|_| {}).build()?;

pub fn idle_spin(self, spin: Duration) -> PoolBuilder

Default spin time of an unreserved idle team member before it returns its thread to Rayon. Defaults to 200 ms; zero returns it immediately.

Operations may override it with WaitOverride. A reserved member never leaves on a timeout.

Examples

use std::time::Duration;

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

pub fn idle_runs_rayon(self, on: bool) -> PoolBuilder

Default for whether unreserved idle members run Rayon jobs while they spin. Defaults to false: native team execution keeps them for the next reservation. true is the compatibility mode in which an idle member serves Rayon work (an acquisition then refuses a member that is inside such a job instead of waiting for it).

Examples

let pool = threadteam::Pool::builder().threads(2).idle_runs_rayon(true).build()?;
assert!(pool.wait_policy().idle_runs_rayon());

pub fn acquire_timeout(self, timeout: Duration) -> PoolBuilder

How long Exec::team waits for idle workers to wake before it refuses. Defaults to 2 ms.

This bounds the wait for workers that are free; the acquisition does not wait for a worker that is running a job, it only runs out this time and refuses. Raise it on a loaded host to reduce spurious refusals.

Examples

use std::time::Duration;
let pool = threadteam::Pool::builder()
    .threads(2)
    .acquire_timeout(Duration::from_millis(10))
    .build()?;

pub fn qos(self, qos: Qos) -> PoolBuilder

Scheduling class of the workers (see [Qos]).

Defaults to [Qos::UserInitiated] on macOS and to nothing elsewhere. The calling thread’s class is not changed by this crate; an engine that wants its leading thread raised too calls raise_current_thread_qos once on it.

Examples

use threadteam::{Pool, Qos};
let pool = Pool::builder().threads(1).qos(Qos::Default).build()?;

pub fn dispatch_costs(self, costs: DispatchCosts) -> PoolBuilder

Overrides the [DispatchCosts] of this pool’s tokens.

Defaults to [DispatchCosts::host_default]. The costs feed Exec::dispatch_cost and everything built on it (pays, width_for); they never change how work is placed.

Examples

use std::num::NonZeroUsize;
use std::time::Duration;
use threadteam::{DispatchCosts, DispatchKind, Exec, HostClass, Pool, WidthCosts};

let costs = DispatchCosts::for_class(HostClass::Generic)
    .with(DispatchKind::Outside, WidthCosts::flat(Duration::from_micros(7)));
let pool = Pool::builder().threads(2).dispatch_costs(costs).build()?;
let exec = Exec::new(&pool, 2)?;
// Without the `parallel` feature the pool has width 1: no section, no cost.
let expected = if pool.width().get() >= 2 { Duration::from_micros(7) } else { Duration::MAX };
assert_eq!(exec.dispatch_cost(NonZeroUsize::new(2).unwrap()), expected);

pub fn build(self) -> Result<Pool, Error>

Starts the workers.

Without the parallel feature no thread is started and the pool has width 1.

Errors

[Error::ZeroThreads] when threads(0) was requested, and [Error::PoolBuild] when the workers cannot be started.

Examples

let pool = threadteam::Pool::builder().threads(2).build()?;
assert!(pool.width().get() <= 2);

Trait Implementations

impl Debug for PoolBuilder

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

Formats the value using the given formatter.