[#BloombergLP-bdlmt-MultiQueueThreadPool]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlmt.adoc[bdlmt]::MultiQueueThreadPool
:relfileprefix: ../../
:mrdocs:

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

== Synopsis

Declared in `<bdlmt_multiqueuethreadpool.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class MultiQueueThreadPool;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/CleanupFunctor.adoc[`CleanupFunctor`] 
| Defines a type alias for the queue cleanup functor type.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/Job.adoc[`Job`] 
| Defines a type alias for the job functor type.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/QueueRegistry.adoc[`QueueRegistry`] 
| Defines a type alias for the registry mapping queue IDs to queues.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/2constructor-01.adoc[`MultiQueueThreadPool`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/2destructor.adoc[`~MultiQueueThreadPool`] [.small]#[destructor]#
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/addJobAtFront-0b.adoc[`addJobAtFront`] 
| `addJobAtFront` overloads
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/batchSize.adoc[`batchSize`] 
| Return an instantaneous snapshot of the execution batch size (see []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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/createQueue.adoc[`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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/deleteQueue-04.adoc[`deleteQueue`] 
| `deleteQueue` overloads
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/disableQueue.adoc[`disableQueue`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/drain.adoc[`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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/drainQueue.adoc[`drainQueue`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/enableQueue.adoc[`enableQueue`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/enqueueJob-0b.adoc[`enqueueJob`] 
| `enqueueJob` overloads
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/isEnabled.adoc[`isEnabled`] 
| 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).
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/isPaused.adoc[`isPaused`] 
| 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).
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/numElements-0f.adoc[`numElements`] 
| `numElements` overloads
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/numProcessed.adoc[`numProcessed`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/numProcessedReset.adoc[`numProcessedReset`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/numQueues.adoc[`numQueues`] 
| Return an instantaneous snapshot of the number of queues managed by this object.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/pauseQueue.adoc[`pauseQueue`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/resumeQueue.adoc[`resumeQueue`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/setBatchSize.adoc[`setBatchSize`] 
| 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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/shutdown.adoc[`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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/start.adoc[`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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/stop.adoc[`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.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/threadPool.adoc[`threadPool`] 
| Return a reference to the non‐modifiable thread pool owned by this object.
| xref:BloombergLP/bdlmt/MultiQueueThreadPool/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<MultiQueueThreadPool, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlmt/MultiQueueThreadPool_Queue.adoc[BloombergLP::bdlmt::MultiQueueThreadPool_Queue]`
| This private class provides a thread‐safe, lightweight job queue.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#