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

Concrete test allocator that tracks memory usage for testing&period;

== Synopsis

Declared in `&lt;bslma&lowbar;testallocator&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class TestAllocator
    : public xref:BloombergLP/bslma/Allocator.adoc[Allocator]
----

== Description

This class defines a concrete &quot;test&quot; allocator mechanism that implements the `Allocator` protocol, and provides instrumentation to track (1) the number of blocks&sol;bytes currently in use, (2) the maximum number of blocks&sol;bytes that have been outstanding at any one time, and (3) the cumulative number of blocks&sol;bytes that have ever been allocated by this test allocator object&period; The accumulated statistics are based solely on the number of bytes requested&period; Additional testing facilities include allocation limits, verbosity modes, status, and automated report printing&period;

Note that, unlike many other allocators, this allocator does NOT rely on the currently installed default allocator (see `bslma&lowbar;default`), but instead &hyphen;&hyphen; by default &hyphen;&hyphen; uses the `MallocFreeAllocator` singleton, which in turn calls the C Standard Library functions `malloc` and `free` as needed&period; Clients may, however, override this allocator by supplying (at construction) any other allocator implementing the `Allocator` protocol&period;

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslma/Allocator.adoc[Allocator]`
| Pure abstract protocol for clients and suppliers of raw memory&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/bslma/TestAllocator/2constructor-0b1.adoc[`TestAllocator`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bslma/TestAllocator/2destructor.adoc[`&#126;TestAllocator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this allocator&period;
| xref:BloombergLP/bslma/Allocator/operator_assign.adoc[`operator&equals;`] 
| 
| xref:BloombergLP/bslma/TestAllocator/allocate-0e.adoc[`allocate`] 
| Return a newly&hyphen;allocated block of memory of the specified `size`&period;
| xref:BloombergLP/bslma/TestAllocator/allocationLimit.adoc[`allocationLimit`] 
| Return the current number of allocation requests left before an exception is thrown&period; A negative value indicates that no exception is scheduled&period;
| xref:BloombergLP/bslma/TestAllocator/deallocate-0c.adoc[`deallocate`] 
| Return the memory block at `address` back to this allocator&period;
| xref:BloombergLP/bslma/Allocator/deleteObject-09.adoc[`deleteObject`] 
| `deleteObject` overloads
| xref:BloombergLP/bslma/Allocator/deleteObjectRaw-06f.adoc[`deleteObjectRaw`] 
| `deleteObjectRaw` overloads
| xref:BloombergLP/bslma/TestAllocator/getFillPattern.adoc[`getFillPattern`] 
| Return the current fill pattern value for this allocator&period; The behavior is undefined unless `hasFillPattern()` returns `true`&period;
| xref:BloombergLP/bslma/TestAllocator/hasFillPattern.adoc[`hasFillPattern`] 
| Return `true` if a fill pattern is currently set for this allocator&period;
| xref:BloombergLP/bslma/TestAllocator/isNoAbort.adoc[`isNoAbort`] 
| Return `true` if this allocator is currently in no&hyphen;abort mode&period;
| xref:BloombergLP/bslma/TestAllocator/isQuiet.adoc[`isQuiet`] 
| Return `true` if this allocator is currently in quiet mode&period;
| xref:BloombergLP/bslma/TestAllocator/isVerbose.adoc[`isVerbose`] 
| Return `true` if this allocator is currently in verbose mode&period;
| xref:BloombergLP/bslma/Allocator/is_equal.adoc[`is&lowbar;equal`] 
| 
| xref:BloombergLP/bslma/TestAllocator/lastAllocateAddress.adoc[`lastAllocateAddress`] 
| Return the allocated memory address of the most recent memory request&period; Return 0 if the request was invalid (e&period;g&period;, allocate non&hyphen; positive number of bytes)&period;
| xref:BloombergLP/bslma/TestAllocator/lastAllocateNumBytes.adoc[`lastAllocateNumBytes`] 
| Return the number of bytes of the most recent memory request&period; Note that this number is always recorded regardless of the validity of the request&period;
| xref:BloombergLP/bslma/TestAllocator/lastAllocatedAddress.adoc[`lastAllocatedAddress`] 
| Return the address that was returned by the most recent allocation request&period; Return 0 if the most recent allocation request was for 0 bytes&period;
| xref:BloombergLP/bslma/TestAllocator/lastAllocatedNumBytes.adoc[`lastAllocatedNumBytes`] 
| Return the number of bytes of the most recent allocation request&period;
| xref:BloombergLP/bslma/TestAllocator/lastDeallocateAddress.adoc[`lastDeallocateAddress`] 
| Return the memory address of the last memory deallocation request&period; Note that the address is always recorded regardless of the validity of the request&period;
| xref:BloombergLP/bslma/TestAllocator/lastDeallocateNumBytes.adoc[`lastDeallocateNumBytes`] 
| Return the number of bytes of the most recent deallocation request&period;
| xref:BloombergLP/bslma/TestAllocator/lastDeallocatedAddress.adoc[`lastDeallocatedAddress`] 
| Return the address supplied to the most recent deallocation request&period;
| xref:BloombergLP/bslma/TestAllocator/lastDeallocatedNumBytes.adoc[`lastDeallocatedNumBytes`] 
| Return the number of bytes of the most recent deallocation request&period;
| xref:BloombergLP/bslma/TestAllocator/name.adoc[`name`] 
| Return the name of this test allocator, or 0 if no name was specified at construction&period;
| xref:BloombergLP/bslma/TestAllocator/numAllocation.adoc[`numAllocation`] 
| Return the cumulative number of allocation requests&period;
| xref:BloombergLP/bslma/TestAllocator/numAllocations.adoc[`numAllocations`] 
| Return the cumulative number of allocation requests&period; Note that this number is incremented for every `allocate` invocation&period;
| xref:BloombergLP/bslma/TestAllocator/numBlocksInUse.adoc[`numBlocksInUse`] 
| Return the number of blocks currently allocated from this object&period; Note that `numBlocksInUse() &lt;&equals; numBlocksMax()`&period;
| xref:BloombergLP/bslma/TestAllocator/numBlocksMax.adoc[`numBlocksMax`] 
| Return the maximum number of blocks ever allocated from this object at any one time&period; Note that `numBlocksInUse() &lt;&equals; numBlocksMax() &lt;&equals; numBlocksTotal()`&period;
| xref:BloombergLP/bslma/TestAllocator/numBlocksTotal.adoc[`numBlocksTotal`] 
| Return the cumulative number of blocks ever allocated from this object&period; Note that `numBlocksMax() &lt;&equals; numBlocksTotal()`&period;
| xref:BloombergLP/bslma/TestAllocator/numBoundsErrors.adoc[`numBoundsErrors`] 
| Return the number of times memory deallocations have detected that pad areas at the front or back of the user segment had been overwritten&period;
| xref:BloombergLP/bslma/TestAllocator/numBytesInUse.adoc[`numBytesInUse`] 
| Return the number of bytes currently allocated from this object&period; Note that `numBytesInUse() &lt;&equals; numBytesMax()`&period;
| xref:BloombergLP/bslma/TestAllocator/numBytesMax.adoc[`numBytesMax`] 
| Return the maximum number of bytes ever allocated from this object at any one time&period; Note that `numBytesInUse() &lt;&equals; numBytesMax() &lt;&equals; numBytesTotal()`&period;
| xref:BloombergLP/bslma/TestAllocator/numBytesTotal.adoc[`numBytesTotal`] 
| Return the cumulative number of bytes ever allocated from this object&period; Note that `numBytesMax() &lt;&equals; numBytesTotal()`&period;
| xref:BloombergLP/bslma/TestAllocator/numDeallocation.adoc[`numDeallocation`] 
| Return the cumulative number of deallocation requests&period;
| xref:BloombergLP/bslma/TestAllocator/numDeallocations.adoc[`numDeallocations`] 
| Return the cumulative number of deallocation requests&period;
| xref:BloombergLP/bslma/TestAllocator/numMismatches.adoc[`numMismatches`] 
| Return the number of mismatched memory deallocations&period;
| xref:BloombergLP/bslma/TestAllocator/print.adoc[`print`] 
| Write the accumulated state information held in this allocator to the optionally specified file `f` (default `stdout`) in a reasonable (multi&hyphen;line) format&period;
| xref:BloombergLP/bslma/TestAllocator/restoreStatistics.adoc[`restoreStatistics`] 
| Restore statistics previously saved by `stashStatistics`&period;
| xref:BloombergLP/bslma/TestAllocator/setAllocationLimit.adoc[`setAllocationLimit`] 
| Set the allocation limit before an exception is thrown to `limit`&period;
| xref:BloombergLP/bslma/TestAllocator/setFillPattern.adoc[`setFillPattern`] 
| Set the fill pattern for newly allocated memory to `pattern`&period;
| xref:BloombergLP/bslma/TestAllocator/setNoAbort.adoc[`setNoAbort`] 
| Set the no&hyphen;abort mode for this test allocator to `flagValue`&period;
| xref:BloombergLP/bslma/TestAllocator/setQuiet.adoc[`setQuiet`] 
| Set the quiet mode for this test allocator to `flagValue`&period;
| xref:BloombergLP/bslma/TestAllocator/setVerbose.adoc[`setVerbose`] 
| Set the verbose mode for this test allocator to `flagValue`&period;
| xref:BloombergLP/bslma/TestAllocator/stashStatistics.adoc[`stashStatistics`] 
| Return the current statistics that may later be passed to `restoreStatistics`, and reset the current statistic as follows&colon;
| xref:BloombergLP/bslma/TestAllocator/status.adoc[`status`] 
| Return a status code summarizing mismatches and outstanding memory&period;
| xref:BloombergLP/bslma/TestAllocator/unsetFillPattern.adoc[`unsetFillPattern`] 
| Unset the fill pattern for this test allocator&period; After calling this method, newly allocated memory will not be initialized with any fill pattern&period;
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/throwBadAlloc.adoc[`throwBadAlloc`] 
| Throw `std&colon;&colon;bad&lowbar;alloc` or abort the program&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 at least `bytes` with `alignment`&period;
| xref:BloombergLP/bslma/Allocator/do_deallocate.adoc[`do&lowbar;deallocate`]  [.small]#[virtual]#
| Return the memory block at `p` having `bytes` and `alignment`&period;
| xref:BloombergLP/bslma/Allocator/do_is_equal.adoc[`do&lowbar;is&lowbar;equal`]  [.small]#[virtual]#
| Return whether this allocator can exchange memory with `other`&period;
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslma/operator_lshift.adoc[BloombergLP::bslma::operator&lt;&lt;]`
| Write the state of `ta` to `stream` and return `stream`&period;
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/operator_not_eq-0a.adoc[`operator!&equals;`]
| Return `true` unless the specified `rhs` is a proxy for `lhs`&period;
| xref:BloombergLP/bslma/operator_eq-0b.adoc[`operator&equals;&equals;`]
| Return `true` if the specified `rhs` is a proxy for the specified `lhs`&period;
|===


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