Class Pool
Defined in File worker-pool.h
Class Documentation
-
class Pool
Declaration:
finalIndependently owned reusable CPU workers.
One thread is the modest default; an application can configure a root pool and obtain multiple logical groups. Destruction closes, drains accepted jobs, and joins its physical threads. Blocking on jobs/drains from this same pool can exhaust its capacity; use external completion checks instead. Pool ownership must outlive its jobs.
Public Functions
-
explicit Pool(std::size_t worker_count = 1)
Start a pool with a strictly positive explicit physical thread count.
See also
- Parameters:
worker_count – Number of threads; unlike PoolOptions, zero is invalid.
- Throws:
CE::Exceptions::invalid_args – For zero count. Native thread/allocation failures propagate after joining any threads already started. No context owns this pool unless explicitly composed.
-
explicit Pool(PoolOptions options)
Discover optional topology and start physical workers.
See also
- Parameters:
options – Owned capacity/provider settings; zero count selects eligible physical cores, eligible logical CPUs or one when unknown. Provider state is retained through shutdown. Discovery/validation/thread creation can fail; partially started threads are joined. Creation does not bind the calling thread or place NUMA memory.
-
~Pool()
Close, drain and join accepted work before releasing provider state.
The caller must settle producers and avoid destruction on this pool’s workers. Jobs must be able to complete without locks or dispatch progress blocked by this caller.
See also
-
Pool(const Pool&) = delete
Copying physical thread ownership is disabled; groups share capacity instead.
See also
-
Pool &operator=(const Pool&) = delete
Replacing physical pool ownership through copy assignment is disabled.
See also
-
Group make_group(GroupOptions options = GroupOptions{})
Declaration:
[[nodiscard]]Publish a logical workload sharing this pool’s physical capacity.
See also
- Parameters:
options – Scheduling share/concurrency and requested CPU/locality constraints.
- Returns:
Copyable group with immutable resolved policy. Thread-safe while the pool lives. Invalid settings, closed pool or unavailable required policy reject; preferred policy may fall back as recorded by policy().
-
inline std::size_t worker_count() const
Declaration:
[[nodiscard]]Read the fixed physical worker capacity; this does not count active or pending jobs.
See also
-
Capabilities capabilities() const
Declaration:
[[nodiscard]]Copy startup capability discovery, not a live query of changing native eligibility.
See also
-
Topology topology() const
Declaration:
[[nodiscard]]Copy retained eligible CPU/core/cache discovery.
Topology IDs belong to this provider snapshot and do not describe NUMA allocation or guarantee cache residency.
See also
-
CE::Diagnostics::DomainId diagnostic_id() const noexcept
Declaration:
[[nodiscard]]Read this physical pool’s process-local diagnostic identity.
See also
-
void report_diagnostics() const noexcept
Emit an explicit startup/capability summary outside outer owner locks.
Reporting is observational and cannot prove placement speedup or completed jobs.
See also
-
void close()
Idempotently stop accepting groups/jobs while allowing accepted work to finish.
Does not join workers or cancel queued jobs; shutdown() completes that lifecycle.
See also
-
void shutdown()
Close, drain and join all physical workers.
Concurrent shutdown callers are serialized; never invoke from this same pool’s worker. Completion requires accepted jobs and capture destructors to progress; no forced thread termination is provided.
See also
-
explicit Pool(std::size_t worker_count = 1)