BloombergLP::bslma::TestAllocator

Name

Description

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.

Name

Description

size_type

Alias for an unsigned integral type capable of representing the number of bytes in this platform's virtual address space.

Name

Description

TestAllocator [constructor]

Constructors

~TestAllocator [destructor] [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).

operator=

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.

allocationLimit

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

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.

deleteObject

deleteObject overloads

deleteObjectRaw

deleteObjectRaw overloads

getFillPattern

Return the current fill pattern value for this allocator. The behavior is undefined unless hasFillPattern() returns true.

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.

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.

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.

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.

is_equal

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

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.

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.

lastAllocatedNumBytes

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

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.

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

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.

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

name

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

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.

numAllocations

Return the cumulative number of allocation requests. Note that this number is incremented for every allocate invocation.

numBlocksInUse

Return the number of blocks currently allocated from this object. Note that numBlocksInUse() <= numBlocksMax().

numBlocksMax

Return the maximum number of blocks ever allocated from this object at any one time. Note that numBlocksInUse() <= numBlocksMax() <= numBlocksTotal().

numBlocksTotal

Return the cumulative number of blocks ever allocated from this object. Note that numBlocksMax() <= numBlocksTotal().

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.

numBytesInUse

Return the number of bytes currently allocated from this object. Note that numBytesInUse() <= numBytesMax().

numBytesMax

Return the maximum number of bytes ever allocated from this object at any one time. Note that numBytesInUse() <= numBytesMax() <= numBytesTotal().

numBytesTotal

Return the cumulative number of bytes ever allocated from this object. Note that numBytesMax() <= numBytesTotal().

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.

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.

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.

print

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

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:

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.

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.

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.

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.

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.

stashStatistics

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

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.

unsetFillPattern

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

Name

Description

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.

Name

Description

do_allocate [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.

do_deallocate [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.

do_is_equal [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.

Name

Description

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.

Name

Description

operator!=

Return true unless the specified rhs is a proxy for the specified lhs, in which case return false.

operator==

Return true if the specified rhs is a proxy for the specified lhs, and false otherwise.