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

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

== Synopsis

Declared in `&lt;bdlma&lowbar;sequentialallocator&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class SequentialAllocator
    : public xref:BloombergLP/bdlma/ManagedAllocator.adoc[ManagedAllocator]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlma/ManagedAllocator.adoc[ManagedAllocator]`
| This protocol class extends `bslma&colon;&colon;Allocator` for allocators with the ability to `release` all memory currently allocated through the protocol back to the memory supplier of the derived concrete allocator object&period;
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/size_type.adoc[`size&lowbar;type`] 
| Alias for an unsigned integral type capable of representing the number of bytes in this platform&apos;s virtual address space&period;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlma/SequentialAllocator/2constructor-0df.adoc[`SequentialAllocator`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlma/SequentialAllocator/2destructor.adoc[`&#126;SequentialAllocator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this sequential allocator&period; All memory allocated from this allocator is released&period;
| xref:BloombergLP/bslma/Allocator/operator_assign.adoc[`operator&equals;`] 
| 
| xref:BloombergLP/bdlma/SequentialAllocator/allocate-04.adoc[`allocate`] 
| `allocate` overloads
| xref:BloombergLP/bdlma/SequentialAllocator/allocateAndExpand.adoc[`allocateAndExpand`] 
| Return the address of a contiguous block of memory of at least the specified `&ast;size` (in bytes), and load the actual amount of memory allocated into `&ast;size`&period; If `&ast;size` is 0, return 0 with no effect&period; 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&period;
| xref:BloombergLP/bdlma/SequentialAllocator/deallocate-034.adoc[`deallocate`] 
| This method has no effect on the memory block at the specified `address` as all memory allocated by this allocator is managed&period; The behavior is undefined unless `address` is 0, or was allocated by this allocator and has not already been deallocated&period;
| xref:BloombergLP/bslma/Allocator/deleteObject-09.adoc[`deleteObject`] 
| `deleteObject` overloads
| xref:BloombergLP/bslma/Allocator/deleteObjectRaw-06f.adoc[`deleteObjectRaw`] 
| `deleteObjectRaw` overloads
| xref:BloombergLP/bslma/Allocator/is_equal.adoc[`is&lowbar;equal`] 
| 
| xref:BloombergLP/bdlma/SequentialAllocator/release.adoc[`release`]  [.small]#[virtual]#
| Release all memory allocated through this allocator and return to the underlying allocator _all_ memory&period; The allocator is reset to its default&hyphen;constructed state, retaining the alignment and growth strategies, and the initial and maximum buffer sizes in effect following construction&period; The effect of subsequently &hyphen; to this invokation of `release` &hyphen; using a pointer obtained from this object prior to this call to `release` is undefined&period;
| xref:BloombergLP/bdlma/SequentialAllocator/reserveCapacity.adoc[`reserveCapacity`] 
| Reserve sufficient memory to satisfy allocation requests for at least the specified `numBytes` without replenishment (i&period;e&period;, without dynamic allocation)&period; If `numBytes` is 0, no memory is reserved&period; Note that, when the `numBytes` is distributed over multiple `allocate` requests &hyphen; due to alignment effects &hyphen; it is possible that not all `numBytes` of memory will be used for allocation before triggering dynamic allocation&period;
| xref:BloombergLP/bdlma/SequentialAllocator/rewind.adoc[`rewind`]  [.small]#[virtual]#
| Release all memory allocated through this allocator and return to the underlying allocator _only_ memory that was allocated outside of the typical internal buffer growth of this allocator (i&period;e&period;, large blocks)&period; All retained memory will be used to satisfy subsequent allocations&period; The effect of subsequently &hyphen; to this invokation of `rewind` &hyphen; using a pointer obtained from this object prior to this call to `rewind` is undefined&period;
| xref:BloombergLP/bdlma/SequentialAllocator/truncate.adoc[`truncate`] 
| Reduce the amount of memory allocated at the specified `address` of the specified `originalSize` (in bytes) to the specified `newSize`&period; Return `newSize` after truncating, or `originalSize` if the memory block at `address` cannot be truncated&period; This method can only `truncate` the memory block returned by the most recent `allocate` request from this allocator, and otherwise has no effect&period; The behavior is undefined unless the memory block at `address` was originally allocated by this allocator, the size of the memory block at `address` is `originalSize`, `newSize &lt;&equals; originalSize`, and `release` was not called after allocating the memory block at `address`&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/throwBadAlloc.adoc[`throwBadAlloc`] 
| Throw `std&colon;&colon;bad&lowbar;alloc` if exceptions are enabled or abort the program otherwise&period; Derived classes and helper functions will typically call this function when they are unable to satisfy an allocation request&period; This function never returns&period;
|===


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/do_allocate.adoc[`do&lowbar;allocate`]  [.small]#[virtual]#
| Return a newly allocated block of memory of (at least) the specified positive `bytes` and having at least the specified `alignment`&period; Unless overriden in a derived class, the return value is `this&hyphen;&gt;allocate(bytes)`&period; If this allocator cannot return the requested number of bytes or cannot satisfy the alignment request, then it will throw a `std&colon;&colon;bad&lowbar;alloc` exception in an exception&hyphen;enabled build, or else will abort the program in a non&hyphen;exception build&period; Unless overriden in a derived class, this function will forward the allocation request to the `allocate` virtual function, padding `bytes` and adjusting the return value as necessary to ensure sufficient alignment&period; Note that if `bytes` is `0`, the same non&hyphen;null value will be returned every time&period;
| xref:BloombergLP/bslma/Allocator/do_deallocate.adoc[`do&lowbar;deallocate`]  [.small]#[virtual]#
| Return the memory block at the specified `p` address, having the specified `bytes` and specified `alignment`, back to this allocator&period; Unless overriden in a derived class, this function will forward the deallocation request to the `deallocate` virtual function, padding `bytes` and adjusting `p` as necessary to account for `alignment` values other than the natural alignment for an object of size `bytes`&period; The behavior is undefined unless `address` is a block allocated from this allocator object using the same `bytes` and `alignment` and not already deallocated&period;
| xref:BloombergLP/bslma/Allocator/do_is_equal.adoc[`do&lowbar;is&lowbar;equal`]  [.small]#[virtual]#
| Return `true` if this allocator is equal to the specified `other` allocator, meaning (at least) that a memory block allocated by one can be deallocated by the other&semi; otherwise return `false`&period; Unless overriden, this method returns `this &equals;&equals; &amp;other`&period;
|===



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