[#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&period; These are intended to synchronize access to another (non&hyphen;atomic) indexed data structure so that the other data structure can be used as a thread&hyphen;enabled fixed&hyphen;size queue&period;

== Synopsis

Declared in `&lt;bdlcc&lowbar;fixedqueueindexmanager&period;h&gt;`

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

== Enums

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


== 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`&period; Optionally specify a `basicAllocator` used to supply memory&period; If `basicAllocator` is 0, the currently installed default allocator is used&period; `isEnabled` will be `true` for the newly created index manager&period; The behavior is undefined unless `0 &lt; capacity` and `capacity &lt;&equals; k&lowbar;MAX&lowbar;CAPACITY`&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/2destructor.adoc[`&#126;FixedQueueIndexManager`] [.small]#[destructor]#
| Destroy this object&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/abortPushIndexReservation.adoc[`abortPushIndexReservation`] 
| Release the specified `index` and make it available for use in the generation following the specified `generation`&period; 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&period; 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&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/capacity.adoc[`capacity`] 
| Return the maximum number of items that may be stored in the queue&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/commitPopIndex.adoc[`commitPopIndex`] 
| Mark the specified `index` as available (empty) in the generation following the specified `generation`&period; The behavior is undefined unless `generation` and index&apos; match those returned by a previous successful call to `reservePopIndex` (that has not previously been committed)&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/commitPushIndex.adoc[`commitPushIndex`] 
| Mark the specified `index` as occupied (full) in the specified `generation`&period; The behavior is undefined unless `generation` and `index` match those returned by a previous successful call to `reservePushIndex` (that has not previously been committed)&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/disable.adoc[`disable`] 
| Mark the queue as disabled&period; Future calls to `reservePushIndex` will fail&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/enable.adoc[`enable`] 
| Mark the queue as enabled&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/isEnabled.adoc[`isEnabled`] 
| Return `true` if the queue is enabled, and `false` if it is disabled&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/length.adoc[`length`] 
| Return a snapshot of the number of items in the queue&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/print.adoc[`print`] 
| Print a formatted string describing the current state of this object to the specified `stream`&period; If `stream` is not valid on entry, this operation has no effect&period; Note that this method describes the internal state of the buffer and is provided purely for debugging purposes&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/reservePopIndex.adoc[`reservePopIndex`] 
| Reserve the next available index from which to dequeue an element from an (externally managed) circular buffer&semi; load the specified `index` with the reserved index and load the specified `generation` with the current generation of the circular buffer&period; Return 0 on success, and a non&hyphen;zero value if the queue is empty&period; 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&semi; clients should call `commitPopIndex` quickly after this method returns, without performing any blocking operations&period; If this method fails the `generation` and `index` will be unmodified&period; The behavior is undefined if the current thread is already holding a reservation on either a push or pop index&period; Note that `generation` is necessary for invoking `commitPopIndex` but should not otherwise be used by the caller&semi; the value reflects the of times the `index` in the circular buffer has been used&period;
| 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&semi; otherwise this operation has no effect&period; Return 0 if an index was successfully reserved, and a non&hyphen;zero value if the current pop index is at `endIndex` and `endGeneration`&period; The behavior is undefined unless `endGeneration` and `endIndex` refer to a cell that has been acquired for writing&period; 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 &hyphen;&hyphen; 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&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/reservePushIndex.adoc[`reservePushIndex`] 
| Reserve the next available index at which to enqueue an element in an (externally managed) circular buffer&semi; load the specified `index` with the reserved index and load the specified `generation` with the current generation of the circular buffer&period; Return 0 on success, a negative value if the queue is disabled, and a positive value if the queue is full&period; 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&semi; clients should call `commitPushIndex` quickly after this method returns, without performing any blocking operations&period; If this method fails the `generation` and `index` will be unmodified&period; The behavior is undefined if the current thread is already holding a reservation on either a push or pop index&period; Note that `generation` is necessary for invoking `commitPushIndex` but should not otherwise be used by the caller&semi; the value reflects the number of times the `index` in the circular buffer has been used&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration&lt;FixedQueueIndexManager, UsesBslmaAllocator&gt;`] 
| Declare that this type uses a `bslma` allocator&period;
|===


== 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 &hyphen; subtrahend`) where minuend and subtrahend are both &quot;circular values&quot;, meaning they are part of a non&hyphen;euclidean number line where the value wrap around to 0 at the specified `modulo`&period; 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&period;e&period;, the minimum &quot;distance&quot; between the points on the number circle), where increments are a positive difference, and decrements are a negative difference&period; If the number of increments and number of decrements between `minuend` and `subtrahend` are equal, `minuend &hyphen; subtrahend` is returned&period; For example, for a hypothetical compass, &lsqb;0, 360)&colon;&rsqb; &grave; circularDifference( 0, 359, 360) &equals;&equals; 1 circularDifference( 359, 0, 360) &equals;&equals; &hyphen;1 circularDifference( 180, 0, 360) &equals;&equals; 180 circularDifference( 0, 180, 360) &equals;&equals; &hyphen;180 &grave; The behavior is undefined unless `minuend &lt; modulo`, `subtrahend &lt; modulo`, and `modulo &lt;&equals; INT&lowbar;MAX &plus; 1`&period;
| xref:BloombergLP/bdlcc/FixedQueueIndexManager/numRepresentableGenerations.adoc[`numRepresentableGenerations`] 
| Return the number of representable generations for a circular buffer of the specified `capacity`&period;
|===



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