#include <bslma_testallocator.h>

Inheritance diagram for bslma::TestAllocator:

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: 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 bslma_testallocator

Public Member Functions
	TestAllocator (Allocator *basicAllocator=0)

	TestAllocator (const char name, Allocator basicAllocator=0)

	TestAllocator (bool verboseFlag, Allocator *basicAllocator=0)

	TestAllocator (const char name, bool verboseFlag, Allocator basicAllocator=0)

	~TestAllocator () BSLS_KEYWORD_OVERRIDE

void *	allocate (size_type size) BSLS_KEYWORD_OVERRIDE

void	deallocate (void *address) BSLS_KEYWORD_OVERRIDE

TestAllocatorStashedStatistics	stashStatistics ()

void	restoreStatistics (TestAllocatorStashedStatistics *savedStatistics)

void	setAllocationLimit (bsls::Types::Int64 limit)

void	setNoAbort (bool flagValue)

void	setQuiet (bool flagValue)

void	setVerbose (bool flagValue)

void	setFillPattern (bsls::Types::Uint64 pattern)

void	unsetFillPattern ()

bsls::Types::Int64	allocationLimit () const

bool	isNoAbort () const

bool	isQuiet () const

bool	isVerbose () const

bool	hasFillPattern () const

bsls::Types::Uint64	getFillPattern () const

void *	lastAllocatedAddress () const

size_type	lastAllocatedNumBytes () const

void *	lastDeallocatedAddress () const

size_type	lastDeallocatedNumBytes () const

const char *	name () const

bsls::Types::Int64	numAllocations () const

bsls::Types::Int64	numBlocksInUse () const

bsls::Types::Int64	numBlocksMax () const

bsls::Types::Int64	numBlocksTotal () const

bsls::Types::Int64	numBoundsErrors () const

bsls::Types::Int64	numBytesInUse () const

bsls::Types::Int64	numBytesMax () const

bsls::Types::Int64	numBytesTotal () const

bsls::Types::Int64	numDeallocations () const

bsls::Types::Int64	numMismatches () const

void	print (std::FILE *f=stdout) const

int	status () const

void *	lastAllocateAddress () const

size_type	lastAllocateNumBytes () const

void *	lastDeallocateAddress () const

size_type	lastDeallocateNumBytes () const

bsls::Types::Int64	numAllocation () const

bsls::Types::Int64	numDeallocation () const

Public Member Functions inherited from bslma::Allocator
	~Allocator () BSLS_KEYWORD_OVERRIDE

template<class TYPE >
void	deleteObject (const TYPE *object)

template<class TYPE >
void	deleteObjectRaw (const TYPE *object)

void	deleteObject (bsl::nullptr_t)

void	deleteObjectRaw (bsl::nullptr_t)

Public Member Functions inherited from bsl::memory_resource
	memory_resource () BSLS_KEYWORD_DEFAULT

	memory_resource (const memory_resource &) BSLS_KEYWORD_DEFAULT

virtual	~memory_resource ()

memory_resource &	operator= (const memory_resource &) BSLS_KEYWORD_DEFAULT

BSLA_NODISCARD void *	allocate (size_t bytes, size_t alignment=k_MAX_ALIGN)

void	deallocate (void *p, size_t bytes, size_t alignment=k_MAX_ALIGN)

bool	is_equal (const memory_resource &other) const BSLS_KEYWORD_NOEXCEPT

Friends
template<class t_OS >
t_OS &	operator<< (t_OS &stream, const TestAllocator &ta)

Additional Inherited Members
Public Types inherited from bslma::Allocator
typedef std::size_t	size_type

Static Public Member Functions inherited from bslma::Allocator
static void	throwBadAlloc ()

Protected Member Functions inherited from bslma::Allocator
void *	do_allocate (std::size_t bytes, std::size_t alignment) BSLS_KEYWORD_OVERRIDE

void	do_deallocate (void *p, std::size_t bytes, std::size_t alignment) BSLS_KEYWORD_OVERRIDE

bool	do_is_equal (const memory_resource &other) const BSLS_KEYWORD_NOEXCEPT BSLS_KEYWORD_OVERRIDE

Constructor & Destructor Documentation

◆ TestAllocator() [1/4]

bslma::TestAllocator::TestAllocator ( Allocator * basicAllocator = 0 )

explicit

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.

◆ TestAllocator() [2/4]

bslma::TestAllocator::TestAllocator	(	const char *	name,
		Allocator *	basicAllocator = `0`
	)

explicit

◆ TestAllocator() [3/4]

bslma::TestAllocator::TestAllocator	(	bool	verboseFlag,
		Allocator *	basicAllocator = `0`
	)

explicit

◆ TestAllocator() [4/4]

bslma::TestAllocator::TestAllocator	(	const char *	name,
		bool	verboseFlag,
		Allocator *	basicAllocator = `0`
	)

◆ ~TestAllocator()

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: 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

◆ allocate()

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; if the allocation fails via an exception, numAllocations() is incremented, lastAllocatedNumBytes() is set to size, and lastDeallocatedAddress() is set to 0.

Implements bslma::Allocator.

◆ allocationLimit()

bsls::Types::Int64 bslma::TestAllocator::allocationLimit ( ) const

inline

Return the current number of allocation requests left before an exception is thrown. A negative value indicates that no exception is scheduled.

◆ deallocate()

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.

◆ getFillPattern()

bsls::Types::Uint64 bslma::TestAllocator::getFillPattern ( ) const

inline

Return the current fill pattern value for this allocator.

Precondition: The behavior is undefined unless hasFillPattern() returns true.

◆ hasFillPattern()

bool bslma::TestAllocator::hasFillPattern ( ) const

inline

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.

◆ isNoAbort()

bool bslma::TestAllocator::isNoAbort ( ) const

inline

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: Note that quiet mode implies no-abort mode.

◆ isQuiet()

bool bslma::TestAllocator::isQuiet ( ) const

inline

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.

◆ isVerbose()

bool bslma::TestAllocator::isVerbose ( ) const

inline

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.

◆ lastAllocateAddress()

void * bslma::TestAllocator::lastAllocateAddress ( ) const

inline

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.

◆ lastAllocatedAddress()

void * bslma::TestAllocator::lastAllocatedAddress ( ) const

inline

Return the address that was returned by the most recent allocation request. Return 0 if the most recent allocation request was for 0 bytes.

◆ lastAllocatedNumBytes()

Allocator::size_type bslma::TestAllocator::lastAllocatedNumBytes ( ) const

inline

Return the number of bytes of the most recent allocation request.

◆ lastAllocateNumBytes()

TestAllocator::size_type bslma::TestAllocator::lastAllocateNumBytes ( ) const

inline

Return the number of bytes of the most recent memory request.

Note: Note that this number is always recorded regardless of the validity of the request.

DEPRECATED: use lastAllocatedNumBytes instead.

◆ lastDeallocateAddress()

void * bslma::TestAllocator::lastDeallocateAddress ( ) const

inline

Return the memory address of the last memory deallocation request.

Note: Note that the address is always recorded regardless of the validity of the request.

DEPRECATED: use lastDeallocatedAddress instead.

◆ lastDeallocatedAddress()

void * bslma::TestAllocator::lastDeallocatedAddress ( ) const

inline

Return the address that was supplied to the most recent deallocation request. Return 0 if a null pointer was most recently deallocated.

Note: Note that the address is always recorded regardless of the validity of the request.

◆ lastDeallocatedNumBytes()

Allocator::size_type bslma::TestAllocator::lastDeallocatedNumBytes ( ) const

inline

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).

◆ lastDeallocateNumBytes()

TestAllocator::size_type bslma::TestAllocator::lastDeallocateNumBytes ( ) const

inline

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.

◆ name()

const char * bslma::TestAllocator::name ( ) const

inline

Return the name of this test allocator, or 0 if no name was specified at construction.

◆ numAllocation()

bsls::Types::Int64 bslma::TestAllocator::numAllocation ( ) const

inline

Return the cumulative number of allocation requests.

Note: Note that this number is incremented for every allocate invocation, regardless of the validity of the request.

DEPRECATED: use numAllocations instead.

◆ numAllocations()

bsls::Types::Int64 bslma::TestAllocator::numAllocations ( ) const

inline

Return the cumulative number of allocation requests.

Note: Note that this number is incremented for every allocate invocation.

◆ numBlocksInUse()

bsls::Types::Int64 bslma::TestAllocator::numBlocksInUse ( ) const

inline

Return the number of blocks currently allocated from this object.

Note: Note that numBlocksInUse() <= numBlocksMax().

◆ numBlocksMax()

bsls::Types::Int64 bslma::TestAllocator::numBlocksMax ( ) const

inline

Return the maximum number of blocks ever allocated from this object at any one time.

Note: Note that numBlocksInUse() <= numBlocksMax() <= numBlocksTotal().

◆ numBlocksTotal()

bsls::Types::Int64 bslma::TestAllocator::numBlocksTotal ( ) const

inline

Return the cumulative number of blocks ever allocated from this object.

Note: Note that numBlocksMax() <= numBlocksTotal().

◆ numBoundsErrors()

bsls::Types::Int64 bslma::TestAllocator::numBoundsErrors ( ) const

inline

Return the number of times memory deallocations have detected that pad areas at the front or back of the user segment had been overwritten.

◆ numBytesInUse()

bsls::Types::Int64 bslma::TestAllocator::numBytesInUse ( ) const

inline

Return the number of bytes currently allocated from this object.

Note: Note that numBytesInUse() <= numBytesMax().

◆ numBytesMax()

bsls::Types::Int64 bslma::TestAllocator::numBytesMax ( ) const

inline

Return the maximum number of bytes ever allocated from this object at any one time.

Note: Note that numBytesInUse() <= numBytesMax() <= numBytesTotal().

◆ numBytesTotal()

bsls::Types::Int64 bslma::TestAllocator::numBytesTotal ( ) const

inline

Return the cumulative number of bytes ever allocated from this object.

Note: Note that numBytesMax() <= numBytesTotal().

◆ numDeallocation()

bsls::Types::Int64 bslma::TestAllocator::numDeallocation ( ) const

inline

Return the cumulative number of deallocation requests.

Note: Note that this number is incremented for every deallocate invocation, regardless of the validity of the request.

DEPRECATED: use numDeallocations instead.

◆ numDeallocations()

bsls::Types::Int64 bslma::TestAllocator::numDeallocations ( ) const

inline

Return the cumulative number of deallocation requests.

Note: Note that this number is incremented for every deallocate invocation, regardless of the validity of the request.

◆ numMismatches()

bsls::Types::Int64 bslma::TestAllocator::numMismatches ( ) const

inline

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.

◆ print()

void bslma::TestAllocator::print ( std::FILE * f = stdout ) const

Write the accumulated state information held in this allocator to the optionally specified file f (default stdout) in a reasonable (multi-line) format.

◆ restoreStatistics()

void bslma::TestAllocator::restoreStatistics ( TestAllocatorStashedStatistics * savedStatistics )

inline

Restore the statistics from the specified savedStatistics by appropriately combining the current values and the saved values.

Precondition: 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:

Statistic	Restore value as
numAllocations	saved + current - saved.numBlocksInUse
numDeallocations	saved.numDeallocations + current.numDeallocations
numMismatches	saved.numMismatches + current.numMismatches
numBoundsErrors	saved.numBoundsErrors + current.numBoundsErrors
numBlocksMax	max(saved.numBlocksMax, current.numBlocksMax)
numBytesMax	max(saved.numBytesMax, current.numBytesMax)
numBlocksTotal	saved + current - saved.numBlocksInUse
numBytesTotal	saved + current - saved.numBytesInUse

◆ setAllocationLimit()

void bslma::TestAllocator::setAllocationLimit ( bsls::Types::Int64 limit )

inline

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.

◆ setFillPattern()

void bslma::TestAllocator::setFillPattern ( bsls::Types::Uint64 pattern )

inline

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: Note that the fill pattern, if set, is applied to the entire user segment of allocated memory blocks.

◆ setNoAbort()

void bslma::TestAllocator::setNoAbort ( bool flagValue )

inline

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

◆ setQuiet()

void bslma::TestAllocator::setQuiet ( bool flagValue )

inline

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

◆ setVerbose()

void bslma::TestAllocator::setVerbose ( bool flagValue )

inline

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: Note that the default mode is not verbose.

◆ stashStatistics()

TestAllocatorStashedStatistics bslma::TestAllocator::stashStatistics ( )

inline

Return the current statistics that may later be passed to restoreStatistics, and reset the current statistic as follows:

Statistic	Reset value to
numAllocations	numBlocksInUse
numDeallocations	ZERO
numMismatches	ZERO
numBoundsErrors	ZERO
numBlocksMax	numBlocksInUse
numBytesMax	numBytesInUse
numBlocksTotal	numBlocksInUse
numBytesTotal	numBytesInUse

◆ status()

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.

◆ unsetFillPattern()

void bslma::TestAllocator::unsetFillPattern ( )

inline

Unset the fill pattern for this test allocator. After calling this method, newly allocated memory will not be initialized with any fill pattern.

Friends And Related Symbol Documentation

◆ operator<<

template<class t_OS >

t_OS & operator<<	(	t_OS &	stream,
		const TestAllocator &	ta
	)

friend

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: Note that std::ostream meets the requirements for t_OS.

The documentation for this class was generated from the following file:

bslma_testallocator.h

Detailed Description

Public Member Functions

Friends

Additional Inherited Members

Constructor & Destructor Documentation

◆ TestAllocator() [1/4]

◆ TestAllocator() [2/4]

◆ TestAllocator() [3/4]

◆ TestAllocator() [4/4]

◆ ~TestAllocator()

Member Function Documentation

◆ allocate()

◆ allocationLimit()

◆ deallocate()

◆ getFillPattern()

◆ hasFillPattern()

◆ isNoAbort()

◆ isQuiet()

◆ isVerbose()

◆ lastAllocateAddress()

◆ lastAllocatedAddress()

◆ lastAllocatedNumBytes()

◆ lastAllocateNumBytes()

◆ lastDeallocateAddress()

◆ lastDeallocatedAddress()

◆ lastDeallocatedNumBytes()

◆ lastDeallocateNumBytes()

◆ name()

◆ numAllocation()

◆ numAllocations()

◆ numBlocksInUse()

◆ numBlocksMax()

◆ numBlocksTotal()

◆ numBoundsErrors()

◆ numBytesInUse()

◆ numBytesMax()

◆ numBytesTotal()

◆ numDeallocation()

◆ numDeallocations()

◆ numMismatches()

◆ print()

◆ restoreStatistics()

◆ setAllocationLimit()

◆ setFillPattern()

◆ setNoAbort()

◆ setQuiet()

◆ setVerbose()

◆ stashStatistics()

◆ status()

◆ unsetFillPattern()

Friends And Related Symbol Documentation

◆ operator<<