[#BloombergLP-bslma-Allocator]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslma.adoc[bslma]::Allocator
:relfileprefix: ../../
:mrdocs:

This protocol class provides a pure abstract interface and contract for clients and suppliers of raw memory. If the requested memory cannot be returned, the contract requires that an `std::bad_alloc` exception be thrown. Note that memory is guaranteed to be sufficiently aligned for any object of the requested size on the current platform, which may be less than the maximal alignment guarantee afforded by global `operator new`.

== Synopsis

Declared in `<bslma_allocator.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class Allocator
    : public std::pmr::memory_resource
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `std::pmr::memory_resource`
| 
|===

== 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/bslma/Allocator/2destructor.adoc[`~Allocator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this allocator. Note that the behavior of destroying an allocator while memory is allocated from it is not specified; unless you _know_ that it is valid to do so, don't!
| xref:BloombergLP/bslma/Allocator/operator_assign.adoc[`operator=`] 
| 
| xref:BloombergLP/bslma/Allocator/allocate-03b.adoc[`allocate`] 
| Return a newly allocated block of memory of the specified `size` bytes.
| xref:BloombergLP/bslma/Allocator/deallocate-04.adoc[`deallocate`] 
| Return the memory block at the specified `address` to this allocator.
| 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`] 
| 
|===


== 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`.
|===


== Derived Classes

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlma/AlignedAllocator.adoc[`AlignedAllocator`] 
| This protocol provides a pure abstract interface and contract for clients and suppliers of raw aligned memory. If the requested memory cannot be returned, the contract requires that an `std::bad_alloc` exception be thrown.
| xref:BloombergLP/bdlma/AligningAllocator.adoc[`AligningAllocator`] 
| This `class` provides a mechanism that serves as a wrapper around another allocator, passed at construction. The mechanism guarantees that all allocations passed to the underlying allocator will be aligned by the alignment specified at construction.
| xref:BloombergLP/bslma/BufferAllocator.adoc[`BufferAllocator`] 
| This `class` provides a concrete buffer allocator that implements the `Allocator` interface, and allocates memory blocks from a fixed‐size buffer that is supplied by the user at construction. The allocator can supply memory that can be maximally (default) or naturally aligned.
| xref:BloombergLP/bdlma/ConcurrentAllocatorAdapter.adoc[`ConcurrentAllocatorAdapter`] 
| This class defines an implementation of the `bslma::Allocator` protocol that "decorates" (wraps) a concrete `bslma::Allocator` to ensure thread‐safe access to the decorated allocator.
| xref:BloombergLP/bdlma/ConcurrentPoolAllocator.adoc[`ConcurrentPoolAllocator`] 
| This class implements the `bslma::Allocator` protocol to provide an allocator that manages pooled memory blocks of some uniform size, specified either at construction, or at the first invocation of the `allocate` method. This allocator maintains an internal linked list of free memory blocks, and dispenses one block for each `allocate` method invocation. When a memory block is deallocated, it is returned to the free list for potential reuse.
| xref:BloombergLP/ball/CountingAllocator.adoc[`CountingAllocator`] 
| This class maintains a count of the total number of allocated bytes. The running byte count is initialized to 0 upon construction, is increased by the `allocate` method, and may be reset to 0 by the `resetNumBytesTotal` method. The `deallocate` method appropriately decrement the byte count. The precise definition of byte count is described in the "Byte Count" section of the component‐level documentation.
| xref:BloombergLP/bdlma/CountingAllocator.adoc[`CountingAllocator`] 
| This class defines a concrete "counting" allocator mechanism that implements the `bslma::Allocator` protocol, and provides instrumentation to track: (1) the number of bytes currently in use, and (2) the cumulative number of bytes that have ever been allocated. The accumulated statistics are based solely on the number of bytes requested (see `allocate`).
| xref:BloombergLP/bdlma/GuardingAllocator.adoc[`GuardingAllocator`] 
| This class defines a concrete thread‐safe "guarding" allocator mechanism that implements the `bslma::Allocator` protocol, and adjoins a read/write protected guard page to each block of memory returned by the `allocate` method. The guard page is placed immediately before or immediately following the block returned from `allocate` according to the `GuardPageLocation` enumerator value (optionally) supplied at construction. Note that, unlike many other allocators, an allocator cannot be (optionally) supplied at construction; instead, a system facility is used that allocates blocks of memory in multiples of the system page size. Also note that this allocator is intended for debugging purposes _only_.
| xref:BloombergLP/bdlma/HeapBypassAllocator.adoc[`HeapBypassAllocator`] 
| This class allows the caller to allocate memory directly from virtual memory, without going through the heap like `malloc` or `new` would. Note that the only way to free any memory allocated with this object is to destroy the object, at which point all memory it has allocated is freed. Thread‐safe.
| xref:BloombergLP/bslma/MallocFreeAllocator.adoc[`MallocFreeAllocator`] 
| This class provides direct access to the system‐supplied (native) global `std::malloc` and `std::free`. A `static` method is provided for obtaining a unique, process wide object of this class, which is valid from the time the method is called until after the program (not just `main`) exits.
| 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.
| xref:BloombergLP/bslma/ManagedAllocator.adoc[`ManagedAllocator`] 
| Provide a protocol 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.
| xref:BloombergLP/bslma/NewDeleteAllocator.adoc[`NewDeleteAllocator`] 
| This class defines a concrete mechanism that adapts the system‐supplied (native) global `operator new` and `operator delete` to the `Allocator` protocol. The class method `singleton` returns a process‐wide unique object of this class whose lifetime is guaranteed to extend from the first call to `singleton` until the program terminates. A second class method, `allocator`, allows for conveniently replacing a "null" allocator with this singleton object. Note that this entire class should generally not be used directly by typical clients (see `bslma_default` for more information).
| xref:BloombergLP/bslma/TestAllocator.adoc[`TestAllocator`] 
| This class defines a concrete "test" allocator mechanism that implements the `Allocator` protocol, and provides instrumentation to track (1) the number of blocks/bytes currently in use, (2) the maximum number of blocks/bytes that have been outstanding at any one time, and (3) the cumulative number of blocks/bytes that have ever been allocated by this test allocator object. The accumulated statistics are based solely on the number of bytes requested. Additional testing facilities include allocation limits, verbosity modes, status, and automated report printing.
|===


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