[#BloombergLP-bdlma-SequentialPool]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlma.adoc[bdlma]::SequentialPool
:relfileprefix: ../../
:mrdocs:

This class implements a fast memory pool that efficiently dispenses heterogeneous blocks of memory (of varying, user‐specified sizes) from a sequence of dynamically‐allocated internal buffers. Memory for the internal buffers is supplied by an (optional) allocator supplied at construction; if no allocator is supplied, the currently installed default allocator is used. If an allocation exceeds the remaining free memory space in the current buffer, the pool replenishes its internal buffer with new memory to satisfy the request. This class is _exception_ _neutral_: If memory cannot be allocated, the behavior is defined by the (optional) allocator specified at construction.

== Synopsis

Declared in `<bdlma_sequentialpool.h>`

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

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlma/SequentialPool/2constructor-0251.adoc[`SequentialPool`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlma/SequentialPool/2destructor.adoc[`~SequentialPool`] [.small]#[destructor]#
| Destroy this sequential pool. All memory allocated by this pool is released.
| xref:BloombergLP/bdlma/SequentialPool/allocate.adoc[`allocate`] 
| Return the address of a contiguous block of memory of the specified `size` (in bytes) according to the alignment strategy specified at construction. If `size` is 0, no memory is allocated and 0 is returned. If the allocation request exceeds the remaining free memory space in the current internal buffer, use the allocator supplied at construction to allocate a new internal buffer, then allocate memory from the new buffer.
| xref:BloombergLP/bdlma/SequentialPool/allocateAndExpand.adoc[`allocateAndExpand`] 
| Return the address of a contiguous block of memory of at least the specified `*size` (in bytes), and load the actual amount of memory allocated in `*size`. If `*size` is 0, return 0 with no effect. If the allocation request exceeds the remaining free memory space in the current internal buffer, use the allocator supplied at construction to allocate a new internal buffer, then allocate memory from the new buffer.
| xref:BloombergLP/bdlma/SequentialPool/allocator.adoc[`allocator`] 
| Return the allocator used by this object to allocate memory. Note that this allocator can not be used to deallocate memory allocated through this pool.
| xref:BloombergLP/bdlma/SequentialPool/deleteObject.adoc[`deleteObject`] 
| Destroy the specified `object`. Note that this method has the same effect as the `deleteObjectRaw` method (since no deallocation is involved), and exists for consistency across pools.
| xref:BloombergLP/bdlma/SequentialPool/deleteObjectRaw.adoc[`deleteObjectRaw`] 
| Destroy the specified `object`. Note that memory associated with `object` is not deallocated because there is no `deallocate` method in `SequentialPool`.
| xref:BloombergLP/bdlma/SequentialPool/release.adoc[`release`] 
| Release all memory allocated through this pool and return to the underlying allocator _all_ memory. The pool is reset to its default‐constructed state, retaining the alignment and growth strategies, and the initial and maximum buffer sizes in effect following construction. The effect of subsequently ‐ to this invocation of `release` ‐ using a pointer obtained from this object prior to this call to `release` is undefined.
| xref:BloombergLP/bdlma/SequentialPool/reserveCapacity.adoc[`reserveCapacity`] 
| Reserve sufficient memory to satisfy allocation requests for at least the specified `numBytes` without replenishment (i.e., without dynamic allocation). If `numBytes` is 0, no memory is reserved. Note that, when the `numBytes` is distributed over multiple `allocate` requests ‐ due to alignment effects ‐ it is possible that not all `numBytes` of memory will be used for allocation before triggering dynamic allocation.
| xref:BloombergLP/bdlma/SequentialPool/rewind.adoc[`rewind`] 
| Release all memory allocated through this pool and return to the underlying allocator _only_ memory that was allocated outside of the typical internal buffer growth of this pool (i.e., large blocks). All retained memory will be used to satisfy subsequent allocations. The effect of subsequently ‐ to this invocation of `rewind` ‐ using a pointer obtained from this object prior to this call to `rewind` is undefined.
| xref:BloombergLP/bdlma/SequentialPool/truncate.adoc[`truncate`] 
| Reduce the amount of memory allocated at the specified `address` of the specified `originalSize` (in bytes) to the specified `newSize`. Return `newSize` after truncating, or `originalSize` if the memory block at `address` cannot be truncated. This method can only `truncate` the memory block returned by the most recent `allocate` request from this memory pool, and otherwise has no effect. The behavior is undefined unless the memory block at `address` was originally allocated by this memory pool, the size of the memory block at `address` is `originalSize`, `newSize <= originalSize`, and `release` was not called after allocating the memory block at `address`.
|===



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