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

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.

== Synopsis

Declared in `<bslma_testallocator.h>`

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

== Description

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

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslma/Allocator.adoc[Allocator]`
| 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`.
|===

== 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/TestAllocator/2constructor-0b1.adoc[`TestAllocator`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bslma/TestAllocator/2destructor.adoc[`~TestAllocator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this allocator. In verbose mode, print all contained state values of this allocator object to `stdout`. Except in quiet mode, automatically report any memory leaks to `stdout`. Abort if either `numBlocksInUse` or `numBytesInUse` return non‐zero unless in no‐abort mode or quiet mode. Note that, in all cases, destroying this object has no effect on outstanding memory blocks allocated from this test allocator (and may result in memory leaks ‐‐ e.g., if the (default) `MallocFreeAllocator` singleton was used).
| xref:BloombergLP/bslma/Allocator/operator_assign.adoc[`operator=`] 
| 
| xref:BloombergLP/bslma/TestAllocator/allocate-0e.adoc[`allocate`] 
| Return a newly‐allocated block of memory of the specified `size` (in bytes). If `size` is 0, a null pointer is returned. Otherwise, invoke the `allocate` method of the allocator supplied at construction, increment the number of currently (and cumulatively) allocated blocks, and increase the number of currently allocated bytes by `size`. Update all other fields accordingly; if the allocation fails via an exception, `numAllocations()` is incremented, `lastAllocatedNumBytes()` is set to `size`, and `lastDeallocatedAddress()` is set to 0.
| xref:BloombergLP/bslma/TestAllocator/allocationLimit.adoc[`allocationLimit`] 
| Return the current number of allocation requests left before an exception is thrown. A negative value indicates that no exception is scheduled.
| xref:BloombergLP/bslma/TestAllocator/deallocate-0c.adoc[`deallocate`] 
| Return the memory block at the specified `address` back to this allocator. If `address` is 0, this function has no effect (other than to record relevant statistics). Otherwise, if the memory at `address` is consistent with being allocated from this test allocator, decrement the number of currently allocated blocks, and decrease the number of currently allocated bytes by the size (in bytes) originally requested for the block. Although technically undefined behavior, if the memory can be determined not to have been allocated from this test allocator, increment the number of mismatches, and ‐‐ unless in quiet mode ‐‐ immediately report the details of the mismatch to `stdout` (e.g., as an `std::hex` memory dump) and abort.
| 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. The behavior is undefined unless `hasFillPattern()` returns `true`.
| xref:BloombergLP/bslma/TestAllocator/hasFillPattern.adoc[`hasFillPattern`] 
| Return `true` if a fill pattern is currently set for this allocator, and `false` otherwise. When a fill pattern is set, newly allocated memory is filled with the pattern value.
| xref:BloombergLP/bslma/TestAllocator/isNoAbort.adoc[`isNoAbort`] 
| Return `true` if this allocator is currently in no‐abort mode, and `false` otherwise. In no‐abort mode all diagnostic messages are printed, but all aborts are suppressed. Note that quiet mode implies no‐abort mode.
| xref:BloombergLP/bslma/TestAllocator/isQuiet.adoc[`isQuiet`] 
| Return `true` if this allocator is currently in quiet mode, and `false` otherwise. In quiet mode, messages about mismatched deallocations, overrun/underrun errors, and memory leaks will not be displayed to `stdout` and will not cause the program to abort.
| xref:BloombergLP/bslma/TestAllocator/isVerbose.adoc[`isVerbose`] 
| Return `true` if this allocator is currently in verbose mode, and `false` otherwise. In verbose mode, all allocation/deallocation events will be reported on `stdout`, as will summary statistics upon destruction of this object.
| xref:BloombergLP/bslma/Allocator/is_equal.adoc[`is_equal`] 
| 
| xref:BloombergLP/bslma/TestAllocator/lastAllocateAddress.adoc[`lastAllocateAddress`] 
| Return the allocated memory address of the most recent memory request. Return 0 if the request was invalid (e.g., allocate non‐ positive number of bytes).
| xref:BloombergLP/bslma/TestAllocator/lastAllocateNumBytes.adoc[`lastAllocateNumBytes`] 
| Return the number of bytes of the most recent memory request. Note that this number is always recorded regardless of the validity of the request.
| xref:BloombergLP/bslma/TestAllocator/lastAllocatedAddress.adoc[`lastAllocatedAddress`] 
| Return the address that was returned by the most recent allocation request. Return 0 if the most recent allocation request was for 0 bytes.
| xref:BloombergLP/bslma/TestAllocator/lastAllocatedNumBytes.adoc[`lastAllocatedNumBytes`] 
| Return the number of bytes of the most recent allocation request.
| xref:BloombergLP/bslma/TestAllocator/lastDeallocateAddress.adoc[`lastDeallocateAddress`] 
| Return the memory address of the last memory deallocation request. Note that the address is always recorded regardless of the validity of the request.
| xref:BloombergLP/bslma/TestAllocator/lastDeallocateNumBytes.adoc[`lastDeallocateNumBytes`] 
| Return the number of bytes of the most recent memory deallocation request. Return 0 if the request was invalid (e.g., deallocating memory not allocated through this allocator).
| xref:BloombergLP/bslma/TestAllocator/lastDeallocatedAddress.adoc[`lastDeallocatedAddress`] 
| Return the address that was supplied to the most recent deallocation request. Return 0 if a null pointer was most recently deallocated. Note that the address is always recorded regardless of the validity of the request.
| xref:BloombergLP/bslma/TestAllocator/lastDeallocatedNumBytes.adoc[`lastDeallocatedNumBytes`] 
| Return the number of bytes of the most recent deallocation request. Return 0 if a null pointer was most recently deallocated, or if the request was invalid (e.g., an attempt to deallocate memory not allocated through this allocator).
| xref:BloombergLP/bslma/TestAllocator/name.adoc[`name`] 
| Return the name of this test allocator, or 0 if no name was specified at construction.
| xref:BloombergLP/bslma/TestAllocator/numAllocation.adoc[`numAllocation`] 
| Return the cumulative number of allocation requests. Note that this number is incremented for every `allocate` invocation, regardless of the validity of the request.
| xref:BloombergLP/bslma/TestAllocator/numAllocations.adoc[`numAllocations`] 
| Return the cumulative number of allocation requests. Note that this number is incremented for every `allocate` invocation.
| xref:BloombergLP/bslma/TestAllocator/numBlocksInUse.adoc[`numBlocksInUse`] 
| Return the number of blocks currently allocated from this object. Note that `numBlocksInUse() <= numBlocksMax()`.
| xref:BloombergLP/bslma/TestAllocator/numBlocksMax.adoc[`numBlocksMax`] 
| Return the maximum number of blocks ever allocated from this object at any one time. Note that `numBlocksInUse() <= numBlocksMax() <= numBlocksTotal()`.
| xref:BloombergLP/bslma/TestAllocator/numBlocksTotal.adoc[`numBlocksTotal`] 
| Return the cumulative number of blocks ever allocated from this object. Note that `numBlocksMax() <= numBlocksTotal()`.
| 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.
| xref:BloombergLP/bslma/TestAllocator/numBytesInUse.adoc[`numBytesInUse`] 
| Return the number of bytes currently allocated from this object. Note that `numBytesInUse() <= numBytesMax()`.
| xref:BloombergLP/bslma/TestAllocator/numBytesMax.adoc[`numBytesMax`] 
| Return the maximum number of bytes ever allocated from this object at any one time. Note that `numBytesInUse() <= numBytesMax() <= numBytesTotal()`.
| xref:BloombergLP/bslma/TestAllocator/numBytesTotal.adoc[`numBytesTotal`] 
| Return the cumulative number of bytes ever allocated from this object. Note that `numBytesMax() <= numBytesTotal()`.
| xref:BloombergLP/bslma/TestAllocator/numDeallocation.adoc[`numDeallocation`] 
| Return the cumulative number of deallocation requests. Note that this number is incremented for every `deallocate` invocation, regardless of the validity of the request.
| xref:BloombergLP/bslma/TestAllocator/numDeallocations.adoc[`numDeallocations`] 
| Return the cumulative number of deallocation requests. Note that this number is incremented for every `deallocate` invocation, regardless of the validity of the request.
| xref:BloombergLP/bslma/TestAllocator/numMismatches.adoc[`numMismatches`] 
| Return the number of mismatched memory deallocations that have occurred since this object was created. A memory deallocation is _mismatched_ if that memory was not allocated directly from this allocator.
| 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‐line) format.
| xref:BloombergLP/bslma/TestAllocator/restoreStatistics.adoc[`restoreStatistics`] 
| Restore the statistics from the specified `savedStatistics` by appropriately combining the current values and the saved values. The behavior is undefined unless `savedStatistics` is a value returned by a previous call to `stashStatictics` on this same object, which has not been passed to `restoreStatistics` yet. This method restores the state of the statistics as if the corresponding `stashStatistics` call has never happened, in the following manner:
| xref:BloombergLP/bslma/TestAllocator/setAllocationLimit.adoc[`setAllocationLimit`] 
| Set the number of valid allocation requests before an exception is to be thrown for this allocator to the specified `limit`. If `limit` is less than 0, no exception is to be thrown. By default, no exception is scheduled.
| xref:BloombergLP/bslma/TestAllocator/setFillPattern.adoc[`setFillPattern`] 
| Set the fill pattern for this test allocator to the specified 64‐bit `pattern`. Newly allocated memory will be filled with the specified pattern value. Note that the fill pattern, if set, is applied to the entire user segment of allocated memory blocks.
| xref:BloombergLP/bslma/TestAllocator/setNoAbort.adoc[`setNoAbort`] 
| Set the no‐abort mode for this test allocator to the specified (boolean) `flagValue`. `If flagValue` is `true`, aborting on fatal errors is suppressed, and the functions simply return. Diagnostics are not affected. Note that the default mode is to abort. Also note that this function is provided primarily to enable visual testing of diagnostic messages produced by this component.
| xref:BloombergLP/bslma/TestAllocator/setQuiet.adoc[`setQuiet`] 
| Set the quiet mode for this test allocator to the specified (boolean) `flagValue`. If `flagValue` is `true`, mismatched allocations, overrun/underrun errors, and memory leak messages will not be displayed to `stdout` and the process will not abort as a result of such conditions. Note that the default mode is _not_ quiet. Also note that this function is provided primarily to enable testing of this component; in quiet mode, situations that would otherwise abort will just quietly increment the `numMismatches` and/or `numBoundsErrors` counters.
| xref:BloombergLP/bslma/TestAllocator/setVerbose.adoc[`setVerbose`] 
| Set the verbose mode for this test allocator to the specified (boolean) `flagValue`. If `flagValue` is `true`, all allocation/deallocation events will be reported automatically on `stdout`, as will accumulated statistics upon destruction of this object. Note that the default mode is _not_ verbose.
| 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:
| xref:BloombergLP/bslma/TestAllocator/status.adoc[`status`] 
| Return 0 on success, and non‐zero otherwise: If there have been any mismatched memory deallocations or over/under runs, return the number of such errors that have occurred as a positive number; if either `0 < numBlocksInUse()` or `0 < numBytesInUse()`, return an arbitrary negative number; else return 0.
| xref:BloombergLP/bslma/TestAllocator/unsetFillPattern.adoc[`unsetFillPattern`] 
| Unset the fill pattern for this test allocator. After calling this method, newly allocated memory will not be initialized with any fill pattern.
|===


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


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslma/operator_lshift.adoc[BloombergLP::bslma::operator<<]`
| Write the accumulated state information held in the specified allocator `ta` to the specified `stream` in a reasonable (multi‐line) format identical to the format produced by `ta.print()` and return a reference offering modifiable access to `stream`. Output is performed via calls to `stream.write(s, count)`, where `write` is a required method of class `t_OS`, `s` is a `const char*` holding the formatted output, and `count` is the length of `s` excluding any null terminator. Note that `std::ostream` meets the requirements for `t_OS`.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/operator_not_eq-0a.adoc[`operator!=`]
| Return `true` unless the specified `rhs` is a proxy for the specified `lhs`, in which case return `false`.
| xref:BloombergLP/bslma/operator_eq-0b.adoc[`operator==`]
| Return `true` if the specified `rhs` is a proxy for the specified `lhs`, and `false` otherwise.
|===


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