[#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‐specified sizes) from a sequence of dynamically‐allocated 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 allocator 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_sequentialallocator.h>`

[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::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.
|===

== Type Aliases

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


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlma/SequentialAllocator/2constructor-0df.adoc[`SequentialAllocator`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlma/SequentialAllocator/2destructor.adoc[`~SequentialAllocator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this sequential allocator. All memory allocated from this allocator is released.
| xref:BloombergLP/bslma/Allocator/operator_assign.adoc[`operator=`] 
| 
| 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 `*size` (in bytes), and load the actual amount of memory allocated into `*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/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. The behavior is undefined unless `address` is 0, or was allocated by this allocator and has not already been deallocated.
| 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_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. The allocator 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 invokation of `release` ‐ using a pointer obtained from this object prior to this call to `release` is undefined.
| xref:BloombergLP/bdlma/SequentialAllocator/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/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.e., large blocks). All retained memory will be used to satisfy subsequent allocations. The effect of subsequently ‐ to this invokation of `rewind` ‐ using a pointer obtained from this object prior to this call to `rewind` is undefined.
| 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`. 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 allocator, and otherwise has no effect. 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 <= originalSize`, and `release` was not called after allocating the memory block at `address`.
|===


== Static Member Functions

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


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/do_allocate.adoc[`do_allocate`]  [.small]#[virtual]#
| Return a newly allocated block of memory of (at least) the specified positive `bytes` and having at least the specified `alignment`. Unless overriden in a derived class, the return value is `this‐>allocate(bytes)`. If this allocator cannot return the requested number of bytes or cannot satisfy the alignment request, then it will throw a `std::bad_alloc` exception in an exception‐enabled build, or else will abort the program in a non‐exception build. 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. Note that if `bytes` is `0`, the same non‐null value will be returned every time.
| xref:BloombergLP/bslma/Allocator/do_deallocate.adoc[`do_deallocate`]  [.small]#[virtual]#
| Return the memory block at the specified `p` address, having the specified `bytes` and specified `alignment`, back to this allocator. 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`. The behavior is undefined unless `address` is a block allocated from this allocator object using the same `bytes` and `alignment` and not already deallocated.
| xref:BloombergLP/bslma/Allocator/do_is_equal.adoc[`do_is_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; otherwise return `false`. Unless overriden, this method returns `this == &other`.
|===



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