#include <bdlmt_threadpool.h>

Detailed Description

This class implements a thread pool used for concurrently executing multiple user-defined functions ("jobs").

Public Types
typedef bsl::function< void()>	Job

Public Member Functions
	BSLMF_NESTED_TRAIT_DECLARATION (ThreadPool, bslma::UsesBslmaAllocator)

	ThreadPool (const bslmt::ThreadAttributes &threadAttributes, int minThreads, int maxThreads, int maxIdleTime, bslma::Allocator *basicAllocator=0)

	ThreadPool (const bslmt::ThreadAttributes &threadAttributes, int minThreads, int maxThreads, int maxIdleTime, const bsl::string_view &threadPoolName, bdlm::MetricsRegistry metricsRegistry, bslma::Allocator basicAllocator=0)

	ThreadPool (const bslmt::ThreadAttributes &threadAttributes, int minThreads, int maxThreads, bsls::TimeInterval maxIdleTime, bslma::Allocator *basicAllocator=0)

	ThreadPool (const bslmt::ThreadAttributes &threadAttributes, int minThreads, int maxThreads, bsls::TimeInterval maxIdleTime, const bsl::string_view &threadPoolName, bdlm::MetricsRegistry metricsRegistry, bslma::Allocator basicAllocator=0)

	~ThreadPool ()

void	drain ()

int	enqueueJob (const Job &functor)

int	enqueueJob (bslmf::MovableRef< Job > functor)

int	enqueueJob (ThreadPoolJobFunc function, void *userData)

double	resetPercentBusy ()

void	shutdown ()

int	start ()

void	stop ()

int	enabled () const

int	maxThreads () const

int	maxIdleTime () const

bsls::TimeInterval	maxIdleTimeInterval () const

int	minThreads () const

int	numActiveThreads () const

int	numPendingJobs () const

int	numWaitingThreads () const

double	percentBusy () const

int	threadFailures () const

Friends
void *	ThreadPoolEntry (void *)

Member Typedef Documentation

◆ Job

typedef bsl::function<void()> bdlmt::ThreadPool::Job

Constructor & Destructor Documentation

◆ ThreadPool() [1/4]

bdlmt::ThreadPool::ThreadPool	(	const bslmt::ThreadAttributes &	threadAttributes,
		int	minThreads,
		int	maxThreads,
		int	maxIdleTime,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a thread pool with the specified threadAttributes, the specified minThreads minimum number of threads, the specified maxThreads maximum number of threads, and the specified maxIdleTime idle time (in milliseconds) after which a thread may be considered for destruction. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The name used for created threads is threadAttributes.threadName() if not empty, otherwise "bdl.ThreadPool".

Precondition: The behavior is undefined unless 0 <= minThreads, minThreads <= maxThreads, and 0 <= maxIdleTime.

◆ ThreadPool() [2/4]

bdlmt::ThreadPool::ThreadPool	(	const bslmt::ThreadAttributes &	threadAttributes,
		int	minThreads,
		int	maxThreads,
		int	maxIdleTime,
		const bsl::string_view &	threadPoolName,
		bdlm::MetricsRegistry *	metricsRegistry,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a thread pool with the specified threadAttributes, the specified minThreads minimum number of threads, the specified maxThreads maximum number of threads, the specified maxIdleTime idle time (in milliseconds) after which a thread may be considered for destruction, the specified threadPoolName to be used to identify this thread pool, and the specified metricsRegistry to be used for reporting metrics. If metricsRegistry is 0, bdlm::MetricsRegistry::singleton() is used. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The name used for created threads is threadAttributes.threadName() if not empty, otherwise threadPoolName if not empty, otherwise "bdl.ThreadPool".

Precondition: The behavior is undefined unless 0 <= minThreads, minThreads <= maxThreads, and 0 <= maxIdleTime.

◆ ThreadPool() [3/4]

bdlmt::ThreadPool::ThreadPool	(	const bslmt::ThreadAttributes &	threadAttributes,
		int	minThreads,
		int	maxThreads,
		bsls::TimeInterval	maxIdleTime,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a thread pool with the specified threadAttributes, the specified minThreads minimum number of threads, the specified maxThreads maximum number of threads, and the specified maxIdleTime idle time after which a thread may be considered for destruction. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The name used for created threads is threadAttributes.threadName() if not empty, otherwise "bdl.ThreadPool".

Precondition: The behavior is undefined unless 0 <= minThreads, minThreads <= maxThreads, 0 <= maxIdleTime, and the maxIdleTime has a value less than or equal to INT_MAX milliseconds.

◆ ThreadPool() [4/4]

bdlmt::ThreadPool::ThreadPool	(	const bslmt::ThreadAttributes &	threadAttributes,
		int	minThreads,
		int	maxThreads,
		bsls::TimeInterval	maxIdleTime,
		const bsl::string_view &	threadPoolName,
		bdlm::MetricsRegistry *	metricsRegistry,
		bslma::Allocator *	basicAllocator = `0`
	)

Construct a thread pool with the specified threadAttributes, the specified minThreads minimum number of threads, the specified maxThreads maximum number of threads, the specified maxIdleTime idle time after which a thread may be considered for destruction, the specified threadPoolName to be used to identify this thread pool, and the specified metricsRegistry to be used for reporting metrics. If metricsRegistry is 0, bdlm::MetricsRegistry::singleton() is used. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The name used for created threads is threadAttributes.threadName() if not empty, otherwise threadPoolName if not empty, otherwise "bdl.ThreadPool".

Precondition: The behavior is undefined unless 0 <= minThreads, minThreads <= maxThreads, 0 <= maxIdleTime, and the maxIdleTime has a value less than or equal to INT_MAX milliseconds.

◆ ~ThreadPool()

bdlmt::ThreadPool::~ThreadPool ( )

Call shutdown() and destroy this thread pool.

Member Function Documentation

◆ BSLMF_NESTED_TRAIT_DECLARATION()

bdlmt::ThreadPool::BSLMF_NESTED_TRAIT_DECLARATION	(	ThreadPool	,
		bslma::UsesBslmaAllocator
	)

◆ drain()

void bdlmt::ThreadPool::drain ( )

Disable queuing on this thread pool and wait until all pending jobs complete. Use start to re-enable queuing.

◆ enabled()

int bdlmt::ThreadPool::enabled ( ) const

inline

Return the state (enabled or not) of the thread pool.

◆ enqueueJob() [1/3]

int bdlmt::ThreadPool::enqueueJob ( bslmf::MovableRef< Job > functor )

◆ enqueueJob() [2/3]

int bdlmt::ThreadPool::enqueueJob ( const Job & functor )

Enqueue the specified functor to be executed by the next available thread. Return 0 if enqueued successfully, and a non-zero value if queuing is currently disabled.

Precondition: The behavior is undefined unless functor is not "unset". See bsl::function for more information on functors.

◆ enqueueJob() [3/3]

int bdlmt::ThreadPool::enqueueJob	(	ThreadPoolJobFunc	function,
		void *	userData
	)

inline

Enqueue the specified function to be executed by the next available thread. The specified userData pointer will be passed to the function by the processing thread. Return 0 if enqueued successfully, and a non-zero value if queuing is currently disabled.

◆ maxIdleTime()

int bdlmt::ThreadPool::maxIdleTime ( ) const

inline

Return the amount of time (in milliseconds) a thread remains idle before being shut down when there are more than min threads started.

◆ maxIdleTimeInterval()

bsls::TimeInterval bdlmt::ThreadPool::maxIdleTimeInterval ( ) const

inline

Return the amount of time a thread remains idle before being shut down when there are more than min threads started.

◆ maxThreads()

int bdlmt::ThreadPool::maxThreads ( ) const

inline

Return the maximum number of threads that are allowed to be running at given time.

◆ minThreads()

int bdlmt::ThreadPool::minThreads ( ) const

inline

Return the minimum number of threads that must be started at any given time.

◆ numActiveThreads()

int bdlmt::ThreadPool::numActiveThreads ( ) const

Return the number of threads that are currently processing a job.

◆ numPendingJobs()

int bdlmt::ThreadPool::numPendingJobs ( ) const

Return the number of jobs that are currently queued, but not yet being processed.

◆ numWaitingThreads()

int bdlmt::ThreadPool::numWaitingThreads ( ) const

Return the number of threads that are currently waiting for a job.

◆ percentBusy()

double bdlmt::ThreadPool::percentBusy ( ) const

Return the percentage of wall time spent by each thread of this thread pool executing jobs since the last reset time. The creation of the thread pool is considered a first reset time. This value is calculated as:

         sum(jobExecutionTime)       100%
P_busy = --------------------   x ----------
          timeSinceLastReset      maxThreads

Note: Note that this percentage reflects the wall time spent per thread, and not CPU time per thread, or not even CPU time per processor. Also note that there is no guarantee that all threads are processed concurrently (e.g., the number of threads could be larger than the number of processors).

◆ resetPercentBusy()

double bdlmt::ThreadPool::resetPercentBusy ( )

Atomically report the percentage of wall time spent by each thread of this thread pool executing jobs since the last reset time, and set the reset time to now. The creation of the thread pool is considered a first reset time. This value is calculated as:

         sum(jobExecutionTime)       100%
P_busy = --------------------   x ----------
          timeSinceLastReset      maxThreads

Note: Note that this percentage reflects the wall time spent per thread, and not CPU time per thread, or not even CPU time per processor. Also note that there is no guarantee that all threads are processed concurrently (e.g., the number of threads could be larger than the number of processors).

◆ shutdown()

void bdlmt::ThreadPool::shutdown ( )

Disable queuing on this thread pool, cancel all queued jobs, and shut down all processing threads (after all active jobs complete).

◆ start()

int bdlmt::ThreadPool::start ( )

Enable queuing on this thread pool and spawn minThreads() processing threads. Return 0 on success, and a non-zero value otherwise. If minThreads() threads were not successfully started, all threads are stopped.

◆ stop()

void bdlmt::ThreadPool::stop ( )

Disable queuing on this thread pool and wait until all pending jobs complete, then shut down all processing threads.

◆ threadFailures()

int bdlmt::ThreadPool::threadFailures ( ) const

inline

Return the number of times that thread creation failed.

Friends And Related Symbol Documentation

◆ ThreadPoolEntry

void * ThreadPoolEntry ( void * )

friend

Entry point for processing threads.

The documentation for this class was generated from the following file:

bdlmt_threadpool.h

Detailed Description

Public Types

Public Member Functions

Friends

Member Typedef Documentation

◆ Job

Constructor & Destructor Documentation

◆ ThreadPool() [1/4]

◆ ThreadPool() [2/4]

◆ ThreadPool() [3/4]

◆ ThreadPool() [4/4]

◆ ~ThreadPool()

Member Function Documentation

◆ BSLMF_NESTED_TRAIT_DECLARATION()

◆ drain()

◆ enabled()

◆ enqueueJob() [1/3]

◆ enqueueJob() [2/3]

◆ enqueueJob() [3/3]

◆ maxIdleTime()

◆ maxIdleTimeInterval()

◆ maxThreads()

◆ minThreads()

◆ numActiveThreads()

◆ numPendingJobs()

◆ numWaitingThreads()

◆ percentBusy()

◆ resetPercentBusy()

◆ shutdown()

◆ start()

◆ stop()

◆ threadFailures()

Friends And Related Symbol Documentation

◆ ThreadPoolEntry