#include <bdlmt_multiqueuethreadpool.h>

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

typedef bsl::function< void()>	CleanupFunctor

typedef bsl::map< int, MultiQueueThreadPool_Queue * >	QueueRegistry

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

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

	MultiQueueThreadPool (ThreadPool threadPool, bslma::Allocator basicAllocator=0)

	~MultiQueueThreadPool ()

int	addJobAtFront (int id, const Job &functor)

int	createQueue ()

int	deleteQueue (int id, const CleanupFunctor &cleanupFunctor)

int	deleteQueue (int id)

int	disableQueue (int id)

void	drain ()

int	drainQueue (int id)

int	enqueueJob (int id, const Job &functor)

int	enableQueue (int id)

void	numProcessedReset (int numExecuted, int numEnqueued, int *numDeleted=0)

int	pauseQueue (int id)

int	resumeQueue (int id)

int	setBatchSize (int id, int batchSize)

void	shutdown ()

int	start ()

void	stop ()

int	batchSize (int id) const

bool	isPaused (int id) const

bool	isEnabled (int id) const

int	numQueues () const

int	numElements () const

int	numElements (int id) const

void	numProcessed (int numExecuted, int numEnqueued, int *numDeleted=0) const

const ThreadPool &	threadPool () const

Friends
class	MultiQueueThreadPool_Queue

Detailed Description

This class implements a dynamic, configurable pool of queues, each of which is processed serially by a thread pool.

See bdlmt_multiqueuethreadpool

Member Typedef Documentation

◆ CleanupFunctor

typedef bsl::function<void()> bdlmt::MultiQueueThreadPool::CleanupFunctor

◆ Job

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

◆ QueueRegistry

typedef bsl::map<int, MultiQueueThreadPool_Queue *> bdlmt::MultiQueueThreadPool::QueueRegistry

Constructor & Destructor Documentation

◆ MultiQueueThreadPool() [1/2]

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

Construct a MultiQueueThreadPool 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 behavior is undefined unless 0 <= minThreads, minThreads <= maxThreads, and 0 <= maxIdleTime. Note that the MultiQueueThreadPool is created without any queues. Although queues may be created, start must be called before enqueuing jobs.

◆ MultiQueueThreadPool() [2/2]

bdlmt::MultiQueueThreadPool::MultiQueueThreadPool	(	ThreadPool *	threadPool,
		bslma::Allocator *	basicAllocator = `0`
	)

explicit

Construct a MultiQueueThreadPool with the specified threadPool. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the default memory allocator is used. The behavior is undefined if threadPool is 0. Note that the MultiQueueThreadPool is created without any queues. Although queues may be created, start must be called before enqueuing jobs.

◆ ~MultiQueueThreadPool()

bdlmt::MultiQueueThreadPool::~MultiQueueThreadPool ( )

Destroy this multi-queue thread pool. Disable queuing on all queues, and wait until all queues are empty. Then, delete all queues, and shut down the thread pool if the thread pool is owned by this object. This method will block if any thread is executing start or stop at the time of the call.

Member Function Documentation

◆ addJobAtFront()

int bdlmt::MultiQueueThreadPool::addJobAtFront	(	int	id,
		const Job &	functor
	)

inline

Add the specified functor at the front of the queue specified by id. Return 0 if added successfully, and a non-zero value if queuing is disabled. The behavior is undefined unless functor is bound. Note that the position of functor relative to any currently queued jobs is unspecified unless the queue is currently paused.

◆ batchSize()

int bdlmt::MultiQueueThreadPool::batchSize ( int id ) const

inline

Return an instantaneous snapshot of the execution batch size (see Job Execution Batch Size of the queue associated with the specified id, or -1 if id is not a valid queue id. When a thread is selecting jobs for processing, if fewer than batchSize jobs are available then only the available jobs will be processed in the current batch.

◆ BSLMF_NESTED_TRAIT_DECLARATION()

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

◆ createQueue()

int bdlmt::MultiQueueThreadPool::createQueue ( )

Create a queue with unlimited capacity and a default number of initial elements. Return a non-zero queue ID. The queue ID can be used to enqueue jobs to the queue, or to control or delete the queue.

◆ deleteQueue() [1/2]

int bdlmt::MultiQueueThreadPool::deleteQueue ( int id )

Disable enqueuing to the queue associated with the specified id, and when the currently executing job (or batch of jobs) of that queue, if any, is complete, then destroy the queue. Return 0 on success, and a non-zero value otherwise. This function will fail if the pool is stopped. Any other (non-executing) jobs on the queue are deleted asynchronously. The calling thread blocks until completion of the currently executing job (or batch of jobs), except when deleteQueue is called from a job in the queue being deleted. In that latter case, no block takes place, the queue is deleted (no longer observable from the MultiQueueThreadPool), and the job completes.

◆ deleteQueue() [2/2]

int bdlmt::MultiQueueThreadPool::deleteQueue	(	int	id,
		const CleanupFunctor &	cleanupFunctor
	)

Disable enqueuing to the queue associated with the specified id, and enqueue the specified cleanupFunctor to the front of the queue. The cleanupFunctor is guaranteed to be the last queue element processed, after which the queue is destroyed. This function does not wait for the cleanupFunctor to be executed (instead the caller is notified asynchronously through the execution of the supplied cleanupFunctor). Return 0 on success, and a non-zero value otherwise. Note that this function will fail if this pool is stopped.

◆ disableQueue()

int bdlmt::MultiQueueThreadPool::disableQueue ( int id )

Disable enqueuing to the queue associated with the specified id. Return 0 on success, and a non-zero value otherwise. Note that this method differs from pauseQueue in that (1) disableQueue does not stop processing for a queue, and (2) prevents additional jobs from being enqueued.

◆ drain()

void bdlmt::MultiQueueThreadPool::drain ( )

Wait until all queues are empty. This method waits until all non-paused queues are empty without disabling the queues (and may thus wait indefinitely). The queues and/or the thread pool may be either enabled or disabled when this method is called. This method may be called on a stopped or started thread pool. Note that drain does not attempt to delete queues directly. However, as a side-effect of emptying all queues, any queue for which deleteQueue was called previously will be deleted before drain returns. Note also that this method waits by repeatedly yielding.

◆ drainQueue()

int bdlmt::MultiQueueThreadPool::drainQueue ( int id )

Wait until all jobs in the queue indicated by the specified id are finished. This method simply waits until that queue is empty, without disabling the queue; it may thus wait indefinitely if more jobs are being added. The queue may be enabled or disabled when this method is called. Return 0 on success, and a non-zero value if the specified queue does not exist or is deleted while this method is waiting. Note that this method waits by repeatedly yielding.

◆ enableQueue()

int bdlmt::MultiQueueThreadPool::enableQueue ( int id )

Enable enqueuing to the queue associated with the specified id. Return 0 on success, and a non-zero value otherwise. It is an error to call enableQueue if a previous call to stop is being executed.

◆ enqueueJob()

int bdlmt::MultiQueueThreadPool::enqueueJob	(	int	id,
		const Job &	functor
	)

inline

Enqueue the specified functor to the queue specified by id. Return 0 if enqueued successfully, and a non-zero value if queuing is disabled. The behavior is undefined unless functor is bound.

◆ isEnabled()

bool bdlmt::MultiQueueThreadPool::isEnabled ( int id ) const

inline

Return true if the queue associated with the specified id is currently enabled, or false otherwise (including if id is not a valid queue id).

◆ isPaused()

bool bdlmt::MultiQueueThreadPool::isPaused ( int id ) const

inline

Return true if the queue associated with the specified id is currently paused, or false otherwise (including if id is not a valid queue id).

◆ numElements() [1/2]

int bdlmt::MultiQueueThreadPool::numElements ( ) const

inline

Return an instantaneous snapshot of the total number of elements enqueued.

◆ numElements() [2/2]

int bdlmt::MultiQueueThreadPool::numElements ( int id ) const

inline

Return an instantaneous snapshot of the number of elements enqueued in the queue associated with the specified id as a non-negative integer, or -1 if id does not specify a valid queue.

◆ numProcessed()

void bdlmt::MultiQueueThreadPool::numProcessed	(	int *	numExecuted,
		int *	numEnqueued,
		int *	numDeleted = `0`
	)		const

inline

Load into the specified numExecuted and numEnqueued the number of items dequeued / enqueued (respectively) since the last time these values were reset. Optionally specify a numDeleted used to load into the number of items deleted since the last time this value was reset.

◆ numProcessedReset()

void bdlmt::MultiQueueThreadPool::numProcessedReset	(	int *	numExecuted,
		int *	numEnqueued,
		int *	numDeleted = `0`
	)

inline

Load into the specified numExecuted and numEnqueued the number of items dequeued / enqueued (respectively) since the last time these values were reset and reset these values. Optionally specify a numDeleted used to load into the number of items deleted since the last time this value was reset. Reset the count of deleted items.

◆ numQueues()

int bdlmt::MultiQueueThreadPool::numQueues ( ) const

inline

Return an instantaneous snapshot of the number of queues managed by this object.

◆ pauseQueue()

int bdlmt::MultiQueueThreadPool::pauseQueue ( int id )

Wait until any currently-executing job (or batch of jobs) on the queue with the specified id completes, then prevent any more jobs from being executed on that queue. Return 0 on success, and a non-zero value if the queue is already paused or is being paused or deleted by another thread. Note that this method may be invoked from a job executing on the given queue, in which case this method does not wait. Note also that this method differs from disableQueue in that (1) pauseQueue stops processing for a queue, and (2) does not prevent additional jobs from being enqueued.

◆ resumeQueue()

int bdlmt::MultiQueueThreadPool::resumeQueue ( int id )

Allow jobs on the queue with the specified id to begin executing. Return 0 on success, and a non-zero value if the queue does not exist or is not paused.

◆ setBatchSize()

int bdlmt::MultiQueueThreadPool::setBatchSize	(	int	id,
		int	batchSize
	)

inline

Configure the queue specified by id to process jobs in groups of the specified batchSize (see {Job Execution Batch Size}). When a thread is selecting jobs for processing, if fewer than batchSize jobs are available then only the available jobs will be processed in the current batch. Return 0 on success, and a non-zero value otherwise. The behavior is undefined unless 1 <= batchSize. Note that the initial value for the execution batch size is 1 for all queues.

◆ shutdown()

void bdlmt::MultiQueueThreadPool::shutdown ( )

Disable queuing on all queues, and wait until all non-paused queues are empty. Then, delete all queues, and shut down the thread pool if the thread pool is owned by this object.

◆ start()

int bdlmt::MultiQueueThreadPool::start ( )

Enable queuing on all queues, start the thread pool if the thread pool is owned by this object, and ensure that at least the minimum number of processing threads are started. Return 0 on success, and a non-zero value otherwise. This method will block if any thread is executing stop or shutdown at the time of the call. This method has no effect if this thread pool has already been started. Note that any paused queues remain paused.

◆ stop()

void bdlmt::MultiQueueThreadPool::stop ( )

Disable queuing on all queues and wait until all non-paused queues are empty. Then, stop the thread pool if the thread pool is owned by this object. Note that stop does not attempt to delete queues directly. However, as a side-effect of emptying all queues, any queue for which deleteQueue was called previously will be deleted before stop unblocks.

◆ threadPool()

const ThreadPool & bdlmt::MultiQueueThreadPool::threadPool ( ) const

inline

Return a reference to the non-modifiable thread pool owned by this object.

Friends And Related Symbol Documentation

◆ MultiQueueThreadPool_Queue

friend class MultiQueueThreadPool_Queue

friend

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

bdlmt_multiqueuethreadpool.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ CleanupFunctor

◆ Job

◆ QueueRegistry

Constructor & Destructor Documentation

◆ MultiQueueThreadPool() [1/2]

◆ MultiQueueThreadPool() [2/2]

◆ ~MultiQueueThreadPool()

Member Function Documentation

◆ addJobAtFront()

◆ batchSize()

◆ BSLMF_NESTED_TRAIT_DECLARATION()

◆ createQueue()

◆ deleteQueue() [1/2]

◆ deleteQueue() [2/2]

◆ disableQueue()

◆ drain()

◆ drainQueue()

◆ enableQueue()

◆ enqueueJob()

◆ isEnabled()

◆ isPaused()

◆ numElements() [1/2]

◆ numElements() [2/2]

◆ numProcessed()

◆ numProcessedReset()

◆ numQueues()

◆ pauseQueue()

◆ resumeQueue()

◆ setBatchSize()

◆ shutdown()

◆ start()

◆ stop()

◆ threadPool()

Friends And Related Symbol Documentation

◆ MultiQueueThreadPool_Queue