bslma_testallocatorstatisticsguard

Detailed Description

Provide mechanism for bslma::TestAllocator scoped statistics.

Outline

• Purpose
• Classes
• Description
  • Statistics
  • Usage
    • Example 1: Determine Maximums for a Scope

Purpose

Provide mechanism for bslma::TestAllocator scoped statistics.

Classes

• bslma::TestAllocatorStatiscticsGuard: bslma::TestAllocator scoped stats

See also

bslma_testallocator

Description

This component provides a single mechanism class, bslma::TestAllocatorStatiscticsGuard, which is used, in concert with bslma::TestAllocator, in the implementation of test drivers. Upon its creation the bslma::TestAllocatorStatiscticsGuard stashes and resets the current statistics state of the specified bslma::TestAllocator so that local values (maximum etc) may be measured in thw scope of the guard. Upon its destruction the guard restores the statistics values of the guarded test allocator to the state what it would have if the guard hasn't been there (as if no stashing and resetting had taken place), but combining the stashed values with the current statistics values of the test allocator.

Statistics

On creation the current statistics are saved to be used later in restoring, and then reset as follows:

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

During destruction the guard restores the state of the statistics, as if the reset (on construction) 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

See also bslma::TestAllocator::stashStatistics and bslma::TestAllocator::restoreStatistics.

Usage

This section illustrates intended use of this component.

Example 1: Determine Maximums for a Scope

Suppose that, in a test driver, we would like to ensure that a certain operation does not use too much memory. However, to do that operation we need to first do something that may or may not use more memory than what we allow. In order for us to be able to measure local maximums (or any statistics) we need to stash and reset the statistics of the used test allocator, and later (at the end of our measured local scope) restore them as if we had never reset them.

First, we define our TestAllocator that we will use throughout:

bslma::TestAllocator testAllocator, *ta = &testAllocator;

Then, we perform the test-preparation operation that may allocate and then release a lot of memory, therefore skewing later statistics:

someOperation(ta);
 
assert(ta->numBlocksMax() - ta->numBlocksInUse() > 4);

Next, we prepare the local statistics by creating a scope and declaring a guard variable:

{
    bslma::TestAllocatorStatisticsGuard tasg(ta);
    assert(ta->numBlocksInUse() == tasg.originalNumBlocksInUse());

Now, we run the measured operation and verify that it has not allocated more than 4 blocks (in addition to what was already allocated before):

    measuredOperation(ta);
    assert(ta->numBlocksMax() - tasg.originalNumBlocksInUse() <= 4);
}

Finally, we demonstrate that the guard restores the statistics:

assert(ta->numBlocksMax() - ta->numBlocksInUse() > 4);