#include <bslma_testallocator.h>
Detailed Description
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.
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.
See Component bslma_testallocator
Member Typedef Documentation
typedef bsls::Types::size_type bslma::Allocator::size_type [inherited] |
Reimplemented in bdlma::ConcurrentPoolAllocator.
Constructor & Destructor Documentation
| bslma::TestAllocator::TestAllocator | ( | Allocator * | basicAllocator = 0 |
) | [explicit] |
| bslma::TestAllocator::TestAllocator | ( | const char * | name, | |
| Allocator * | basicAllocator = 0 | |||
| ) | [explicit] |
| bslma::TestAllocator::TestAllocator | ( | bool | verboseFlag, | |
| Allocator * | basicAllocator = 0 | |||
| ) | [explicit] |
| bslma::TestAllocator::TestAllocator | ( | const char * | name, | |
| bool | verboseFlag, | |||
| Allocator * | basicAllocator = 0 | |||
| ) |
Create an instrumented "test" allocator. Optionally specify a name (associated with this object) to be included in diagnostic messages written to stdout, thereby distinguishing this test allocator from others that might be used in the same program. If name is 0 (or not specified), no distinguishing name is incorporated in diagnostics. Optionally specify a verboseFlag indicating whether this test allocator should automatically report all allocation/deallocation events to stdout and print accumulated statistics on destruction. If verboseFlag is false (or not specified), allocation/deallocation and summary messages will not be written automatically. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the MallocFreeAllocator singleton is used.
| bslma::TestAllocator::~TestAllocator | ( | ) |
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).
Member Function Documentation
| void* bslma::TestAllocator::allocate | ( | size_type | size | ) | [virtual] |
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.
Implements bslma::Allocator.
| void bslma::TestAllocator::deallocate | ( | void * | address | ) | [virtual] |
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.
Implements bslma::Allocator.
| void bslma::TestAllocator::setAllocationLimit | ( | bsls::Types::Int64 | limit | ) |
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.
| void bslma::TestAllocator::setNoAbort | ( | bool | flagValue | ) |
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.
| void bslma::TestAllocator::setQuiet | ( | bool | flagValue | ) |
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.
| void bslma::TestAllocator::setVerbose | ( | bool | flagValue | ) |
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.
| bsls::Types::Int64 bslma::TestAllocator::allocationLimit | ( | ) | const |
Return the current number of allocation requests left before an exception is thrown. A negative value indicates that no exception is scheduled.
| bool bslma::TestAllocator::isNoAbort | ( | ) | const |
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.
| bool bslma::TestAllocator::isQuiet | ( | ) | const |
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.
| bool bslma::TestAllocator::isVerbose | ( | ) | const |
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.
| void* bslma::TestAllocator::lastAllocatedAddress | ( | ) | const |
Return the address that was returned by the most recent allocation request. Return 0 if the most recent allocation request was for 0 bytes.
| size_type bslma::TestAllocator::lastAllocatedNumBytes | ( | ) | const |
Return the number of bytes of the most recent allocation request.
| void* bslma::TestAllocator::lastDeallocatedAddress | ( | ) | const |
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.
| size_type bslma::TestAllocator::lastDeallocatedNumBytes | ( | ) | const |
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).
| const char* bslma::TestAllocator::name | ( | ) | const |
Return the name of this test allocator, or 0 if no name was specified at construction.
| bsls::Types::Int64 bslma::TestAllocator::numAllocations | ( | ) | const |
Return the cumulative number of allocation requests. Note that this number is incremented for every allocate invocation.
| bsls::Types::Int64 bslma::TestAllocator::numBlocksInUse | ( | ) | const |
Return the number of blocks currently allocated from this object. Note that numBlocksInUse() <= numBlocksMax().
| bsls::Types::Int64 bslma::TestAllocator::numBlocksMax | ( | ) | const |
Return the maximum number of blocks ever allocated from this object at any one time. Note that numBlocksInUse() <= numBlocksMax() <= numBlocksTotal().
| bsls::Types::Int64 bslma::TestAllocator::numBlocksTotal | ( | ) | const |
Return the cumulative number of blocks ever allocated from this object. Note that numBlocksMax() <= numBlocksTotal().
| bsls::Types::Int64 bslma::TestAllocator::numBoundsErrors | ( | ) | const |
Return the number of times memory deallocations have detected that pad areas at the front or back of the user segment had been overwritten.
| bsls::Types::Int64 bslma::TestAllocator::numBytesInUse | ( | ) | const |
Return the number of bytes currently allocated from this object. Note that numBytesInUse() <= numBytesMax().
| bsls::Types::Int64 bslma::TestAllocator::numBytesMax | ( | ) | const |
Return the maximum number of bytes ever allocated from this object at any one time. Note that numBytesInUse() <= numBytesMax() <= numBytesTotal().
| bsls::Types::Int64 bslma::TestAllocator::numBytesTotal | ( | ) | const |
Return the cumulative number of bytes ever allocated from this object. Note that numBytesMax() <= numBytesTotal().
| bsls::Types::Int64 bslma::TestAllocator::numDeallocations | ( | ) | const |
Return the cumulative number of deallocation requests. Note that this number is incremented for every deallocate invocation, regardless of the validity of the request.
| bsls::Types::Int64 bslma::TestAllocator::numMismatches | ( | ) | const |
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.
| void bslma::TestAllocator::print | ( | ) | const |
Write the accumulated state information held in this allocator to stdout in some reasonable (multi-line) format.
| int bslma::TestAllocator::status | ( | ) | const |
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.
| void* bslma::TestAllocator::lastAllocateAddress | ( | ) | const |
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).
DEPRECATED: use lastAllocatedAddress instead.
| size_type bslma::TestAllocator::lastAllocateNumBytes | ( | ) | const |
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.
DEPRECATED: use lastAllocatedNumBytes instead.
| void* bslma::TestAllocator::lastDeallocateAddress | ( | ) | const |
Return the memory address of the last memory deallocation request. Note that the address is always recorded regardless of the validity of the request.
DEPRECATED: use lastDeallocatedAddress instead.
| size_type bslma::TestAllocator::lastDeallocateNumBytes | ( | ) | const |
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).
DEPRECATED: use lastDeallocatedNumBytes instead.
| bsls::Types::Int64 bslma::TestAllocator::numAllocation | ( | ) | const |
Return the cumulative number of allocation requests. Note that this number is incremented for every allocate invocation, regardless of the validity of the request.
DEPRECATED: use numAllocations instead.
| bsls::Types::Int64 bslma::TestAllocator::numDeallocation | ( | ) | const |
Return the cumulative number of deallocation requests. Note that this number is incremented for every deallocate invocation, regardless of the validity of the request.
DEPRECATED: use numDeallocations instead.
| static void bslma::Allocator::throwBadAlloc | ( | ) | [static, inherited] |
DEPRECATED: Use bsls::BslExceptionUtil::throwBadAlloc instead.
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.
| void bslma::Allocator::deleteObject | ( | const TYPE * | object | ) | [inherited] |
Destroy the specified object based on its dynamic type and then use this allocator to deallocate its memory footprint. Do nothing if object is a null pointer. The behavior is undefined unless object, when cast appropriately to void *, was allocated using this allocator and has not already been deallocated. Note that dynamic_cast<void *>(object) is applied if TYPE is polymorphic, and static_cast<void *>(object) is applied otherwise.
| void bslma::Allocator::deleteObject | ( | bsl::nullptr_t | ) | [inherited] |
This function has no effect. Note that it exists to support calling deleteObject will a null pointer literal, that would otherwise not deduce to a pointer type for the method above. As calls to deleteObject with (typed) null pointer values have well-defined behavior, it should also support calls with a null pointer literal.
| void bslma::Allocator::deleteObjectRaw | ( | const TYPE * | object | ) | [inherited] |
Destroy the specified object and then use this allocator to deallocate its memory footprint. Do nothing if object is a null pointer. The behavior is undefined unless object was allocated using this allocator, is not a secondary base class pointer -- i.e., the address is (numerically) the same as when it was originally dispensed by this allocator, and has not already been deallocated.
| void bslma::Allocator::deleteObjectRaw | ( | bsl::nullptr_t | ) | [inherited] |
This function has no effect. Note that it exists to support calling deleteObjectRaw will a null pointer literal, that would otherwise not deduce to a pointer type for the method above. As calls to deleteObjectRaw with (typed) null pointer values have well-defined behavior, it should also support calls with a null pointer literal.
The documentation for this class was generated from the following file:
Generated on Fri Mar 31 2023 13:30:05 for BDE Release 3.115.0.0 Production Release by
1.7.1