Struct PoolConfig 

pub struct PoolConfig { /* private fields */ }

Thread pool configuration.

A builder: start from Default (cores − 1 workers, at least 1) and override what the engine needs. Errors are reported by validate, which ThreadPool::new calls for you.

use std::time::Duration;
use pragma_jobs::{PoolConfig, ShutdownPolicy, ThreadPool};
use pragma_jobs::sys::ThreadPriority;

let config = PoolConfig::default()
    .with_workers(4)
    .with_name_prefix("game-worker")
    .with_background_limit(Some(1)) // streaming never takes more than one worker
    .with_shutdown(ShutdownPolicy::Cancel)
    .with_watchdog(Some(Duration::from_millis(500)))
    .with_thread_priority(Some(ThreadPriority::Normal));
assert_eq!(config.background_limit(), 1);

let pool = ThreadPool::new(config)?;
assert_eq!(pool.workers(), 4);

Implementations

impl PoolConfig

pub fn with_workers(self, workers: usize) -> PoolConfig

Sets the number of worker threads.

pub fn with_name_prefix(self, prefix: impl Into<String>) -> PoolConfig

Thread name prefix (visible in the profiler and the debugger): <prefix>-<index>.

pub fn with_stack_size(self, bytes: Option<usize>) -> PoolConfig

Worker thread stack size in bytes (None: the OS default).

pub fn with_background_limit(self, limit: Option<usize>) -> PoolConfig

How many workers may run Priority::Background tasks at the same time (None: half of the workers, rounded up).

pub fn with_shutdown(self, policy: ShutdownPolicy) -> PoolConfig

Shutdown policy when the pool is dropped.

pub fn with_watchdog(self, threshold: Option<Duration>) -> PoolConfig

Watchdog for stuck tasks (debug builds only): a labeled task (labeled: graph tasks, spawn, async) running on a pool thread longer than threshold produces one warning in the log (tracing::warn!, target pragma_jobs::watchdog) with the task and thread names. None disables it.

Defaults to DEFAULT_WATCHDOG. In a release build the setting is ignored: there is neither a watchdog thread nor task bookkeeping.

pub fn with_thread_priority( self, priority: Option<ThreadPriority>, ) -> PoolConfig

OS priority of the worker threads (None: leave unchanged). If the OS refuses (for example raising it on Linux without CAP_SYS_NICE), the worker logs a warning and runs with its previous priority.

pub fn with_affinity(self, cores: Option<Vec<usize>>) -> PoolConfig

Pins workers to logical cores: worker i is pinned to core cores[i % cores.len()] (None: no pinning, the OS decides). A pinning error is a warning in the log; the worker runs without it.

use pragma_jobs::PoolConfig;

// Leave core 0 to the main thread, spread 4 workers over cores 1..=3.
let config = PoolConfig::default().with_workers(4).with_affinity(Some(vec![1, 2, 3]));
assert_eq!(config.core_for(0), Some(1));
assert_eq!(config.core_for(3), Some(1)); // wraps around

pub fn with_idle_spin(self, rounds: u32) -> PoolConfig

How many yield rounds an idle worker searches for work before going to sleep (after a short spin). More rounds pick up the next wave of work (a frame, a nested join) faster, but keep the CPU busy doing nothing for longer; 0 parks right after the spin. The default DEFAULT_IDLE_SPIN was tuned with benchmarks (docs/perf.md).

pub fn idle_spin(&self) -> u32

yield rounds before parking.

pub fn watchdog(&self) -> Option<Duration>

The watchdog threshold (effective in debug builds only).

pub fn thread_priority(&self) -> Option<ThreadPriority>

Priority of the worker threads.

pub fn core_for(&self, index: usize) -> Option<usize>

The core for worker index, if pinning is configured.

pub fn workers(&self) -> usize

Number of worker threads.

pub fn name_prefix(&self) -> &str

Thread name prefix.

pub fn stack_size(&self) -> Option<usize>

Worker thread stack size.

pub fn background_limit(&self) -> usize

The worker limit for background tasks, with the default applied.

pub fn shutdown(&self) -> ShutdownPolicy

The shutdown policy.

pub fn validate(self) -> Result<PoolConfig, JobsError>

Validates the configuration before threads are started.

Rules: 1..=512 workers, a non-zero stack size, a background limit in 1..=workers, a non-zero watchdog threshold, a non-empty affinity list.

use pragma_jobs::{JobsError, PoolConfig};

let err = PoolConfig::default()
    .with_workers(2)
    .with_background_limit(Some(3))
    .validate()
    .unwrap_err();
assert!(matches!(err, JobsError::InvalidConfig { .. }));
assert!(PoolConfig::default().validate().is_ok());

Trait Implementations

impl Clone for PoolConfig

fn clone(&self) -> PoolConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PoolConfig

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

Formats the value using the given formatter.

impl Default for PoolConfig

fn default() -> PoolConfig

Number of workers = logical cores − 1 (the main thread runs tasks too), at least 1.

impl Eq for PoolConfig

impl PartialEq for PoolConfig

fn eq(&self, other: &PoolConfig) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PoolConfig