[#BloombergLP-bdlcc-FixedQueueIndexManager]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlcc.adoc[bdlcc]::FixedQueueIndexManager
:relfileprefix: ../../
:mrdocs:

This class implements a circular buffer of atomic state variables. These are intended to synchronize access to another (non‐atomic) indexed data structure so that the other data structure can be used as a thread‐enabled fixed‐size queue.

== Synopsis

Declared in `<bdlcc_fixedqueueindexmanager.h>`

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

== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/_04enum.adoc[`Unnamed enum`] 
| Capacity‐related constants for this index manager.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/2constructor.adoc[`FixedQueueIndexManager`]         [.small]#[constructor]#
| Create an index manager for a circular buffer having the specified maximum `capacity`. Optionally specify a `basicAllocator` used to supply memory. If `basicAllocator` is 0, the currently installed default allocator is used. `isEnabled` will be `true` for the newly created index manager. The behavior is undefined unless `0 < capacity` and `capacity <= k_MAX_CAPACITY`.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/2destructor.adoc[`~FixedQueueIndexManager`] [.small]#[destructor]#
| Destroy this object.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/abortPushIndexReservation.adoc[`abortPushIndexReservation`] 
| Release the specified `index` and make it available for use in the generation following the specified `generation`. The behavior is undefined unless the calling thread holds a reservation on `generation` and `index`, and `clearPopIndex` and then `commitPushIndex` have been repeatedly invoked with `generation` and `index` as input until no indices remain to clear. Note that this operation is used to facilitate removing all the elements in a circular buffer if an exception is thrown between reserving an index for pushing, and committing that index.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/capacity.adoc[`capacity`] 
| Return the maximum number of items that may be stored in the queue.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/commitPopIndex.adoc[`commitPopIndex`] 
| Mark the specified `index` as available (empty) in the generation following the specified `generation`. The behavior is undefined unless `generation` and index' match those returned by a previous successful call to `reservePopIndex` (that has not previously been committed).
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/commitPushIndex.adoc[`commitPushIndex`] 
| Mark the specified `index` as occupied (full) in the specified `generation`. The behavior is undefined unless `generation` and `index` match those returned by a previous successful call to `reservePushIndex` (that has not previously been committed).
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/disable.adoc[`disable`] 
| Mark the queue as disabled. Future calls to `reservePushIndex` will fail.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/enable.adoc[`enable`] 
| Mark the queue as enabled.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/isEnabled.adoc[`isEnabled`] 
| Return `true` if the queue is enabled, and `false` if it is disabled.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/length.adoc[`length`] 
| Return a snapshot of the number of items in the queue.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/print.adoc[`print`] 
| Print a formatted string describing the current state of this object to the specified `stream`. If `stream` is not valid on entry, this operation has no effect. Note that this method describes the internal state of the buffer and is provided purely for debugging purposes.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/reservePopIndex.adoc[`reservePopIndex`] 
| Reserve the next available index from which to dequeue an element from an (externally managed) circular buffer; load the specified `index` with the reserved index and load the specified `generation` with the current generation of the circular buffer. Return 0 on success, and a non‐zero value if the queue is empty. If this method succeeds, other threads using this object may spin on the corresponding index state until `commitPopIndex` is called using the returned `index` and `generation` values; clients should call `commitPopIndex` quickly after this method returns, without performing any blocking operations. If this method fails the `generation` and `index` will be unmodified. The behavior is undefined if the current thread is already holding a reservation on either a push or pop index. Note that `generation` is necessary for invoking `commitPopIndex` but should not otherwise be used by the caller; the value reflects the of times the `index` in the circular buffer has been used.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/reservePopIndexForClear.adoc[`reservePopIndexForClear`] 
| If the next available index from which an element can be popped is before the specified `endGeneration` and `endIndex` then reserve that index for popping and load the specified `disposedGeneration` and `disposedIndex` with the generation and index of the reserved cell; otherwise this operation has no effect. Return 0 if an index was successfully reserved, and a non‐zero value if the current pop index is at `endIndex` and `endGeneration`. The behavior is undefined unless `endGeneration` and `endIndex` refer to a cell that has been acquired for writing. Note that this operation is used to facilitate removing all the elements in a circular buffer if an exception is thrown between reserving an index for pushing, and committing that index ‐‐ the intended usage is to call `reservePopIndexForClear` and then `commitPopIndex`, emptying all the cells up to the index that was reserved for writing, and then call `abortPushIndexReservation` on the reserved index.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/reservePushIndex.adoc[`reservePushIndex`] 
| Reserve the next available index at which to enqueue an element in an (externally managed) circular buffer; load the specified `index` with the reserved index and load the specified `generation` with the current generation of the circular buffer. Return 0 on success, a negative value if the queue is disabled, and a positive value if the queue is full. If this method succeeds, other threads using this object may spin on the corresponding index state until `commitPushIndex` is called using the returned `index` and `generation` values; clients should call `commitPushIndex` quickly after this method returns, without performing any blocking operations. If this method fails the `generation` and `index` will be unmodified. The behavior is undefined if the current thread is already holding a reservation on either a push or pop index. Note that `generation` is necessary for invoking `commitPushIndex` but should not otherwise be used by the caller; the value reflects the number of times the `index` in the circular buffer has been used.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<FixedQueueIndexManager, UsesBslmaAllocator>`] 
| Declare that this type uses a `bslma` allocator.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/circularDifference.adoc[`circularDifference`] 
| Return the difference between the specified `minuend` and the specified `subtrahend` (typically `minuend ‐ subtrahend`) where minuend and subtrahend are both "circular values", meaning they are part of a non‐euclidean number line where the value wrap around to 0 at the specified `modulo`. The difference between two circular values is the minimum of either the number of increments or the number of decrements to `subtrahend` that results in `minuend` (i.e., the minimum "distance" between the points on the number circle), where increments are a positive difference, and decrements are a negative difference. If the number of increments and number of decrements between `minuend` and `subtrahend` are equal, `minuend ‐ subtrahend` is returned. For example, for a hypothetical compass, [0, 360):] ` circularDifference( 0, 359, 360) == 1 circularDifference( 359, 0, 360) == ‐1 circularDifference( 180, 0, 360) == 180 circularDifference( 0, 180, 360) == ‐180 ` The behavior is undefined unless `minuend < modulo`, `subtrahend < modulo`, and `modulo <= INT_MAX + 1`.
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/numRepresentableGenerations.adoc[`numRepresentableGenerations`] 
| Return the number of representable generations for a circular buffer of the specified `capacity`.
|===



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