std.experimental.allocator.building_blocks.stats_collector

Allocator that collects useful statistics about allocations, both global and per calling point. The statistics collected can be configured statically by choosing combinations of Options appropriately.

Source: std/experimental/allocator/building_blocks/stats_collector.d

enum Options

struct StatsCollector

Types 2

enumOptions : ulong

_Options for StatsCollector defined below. Each enables during compilation one specific counter, statistic, or other piece of information.

numOwns = 1u << 0Counts the number of calls to `owns`.

numAllocate = 1u << 1Counts the number of calls to `allocate`. All calls are counted, including requests for zero bytes or failed requests.

numAllocateOK = 1u << 2Counts the number of calls to `allocate` that succeeded, i.e. they returned a block as large as requested. (N.B. requests for zero bytes count as successful.)

numExpand = 1u << 3Counts the number of calls to `expand`, regardless of arguments or result.

numExpandOK = 1u << 4Counts the number of calls to `expand` that resulted in a successful expansion.

numReallocate = 1u << 5Counts the number of calls to `reallocate`, regardless of arguments or result.

numReallocateOK = 1u << 6Counts the number of calls to `reallocate` that succeeded. (Reallocations to zero bytes count as successful.)

numReallocateInPlace = 1u << 7Counts the number of calls to `reallocate` that resulted in an in-place reallocation (no memory moved). If this number is close to the total number of reallocations, that indicates the allocator fi...

numDeallocate = 1u << 8Counts the number of calls to `deallocate`.

numDeallocateAll = 1u << 9Counts the number of calls to `deallocateAll`.

numAlignedAllocate = 1u << 10Counts the number of calls to `alignedAllocate`. All calls are counted, including requests for zero bytes or failed requests.

numAlignedAllocateOk = 1u << 11Counts the number of calls to `alignedAllocate` that succeeded, i.e. they returned a block as large as requested. (N.B. requests for zero bytes count as successful.)

numAll = (1u << 12) - 1Chooses all `numXxx` flags.

bytesUsed = 1u << 12Tracks bytes currently allocated by this allocator. This number goes up and down as memory is allocated and deallocated, and is zero if the allocator currently has no active allocation.

bytesAllocated = 1u << 13Tracks total cumulative bytes allocated by means of `allocate`, `expand`, and `reallocate` (when resulting in an expansion). This number always grows and indicates allocation traffic. To compute by...

bytesExpanded = 1u << 14Tracks the sum of all `delta` values in calls of the form expand(b) that succeed (return `true`).

bytesContracted = 1u << 15Tracks the sum of all b.length - s with b.length > s in calls of the form realloc(b) that succeed (return `true`). In per-call statistics, also unambiguously counts the bytes deallocated with `deal...

bytesMoved = 1u << 16Tracks the sum of all bytes moved as a result of calls to `realloc` that were unable to reallocate in place. A large number (relative to bytesAllocated) indicates that the application should use la...

bytesNotMoved = 1u << 17Tracks the sum of all bytes NOT moved as result of calls to `realloc` that managed to reallocate in place. A large number (relative to bytesAllocated) indicates that the application is expansion-in...

bytesSlack = 1u << 18Measures the sum of extra bytes allocated beyond the bytes requested, i.e. the en.wikipedia.org/wiki/Fragmentation(computing#Internalfragmentation, internal fragmentation). This is the current effe...

bytesHighTide = 1u << 19Measures the maximum bytes allocated over the time. This is useful for dimensioning allocators.

bytesAll = ((1u << 20) - 1) & ~ numAllChooses all `byteXxx` flags.

all = (1u << 20) - 1Combines all flags above.

structStatsCollector(Allocator, ulong flags = Options.all, ulong perCallFlags = 0)

Allocator that collects extra data about allocations. Since each piece of information adds size and time overhead, statistics can be individually enabled or disabled through compile-time flags.

All stats of the form numXxx record counts of events occurring, such as calls to functions and specific results. The stats of the form bytesXxx collect cumulative sizes.

In addition, the data callerSize, callerModule, callerFile, callerLine, and callerTime is associated with each specific allocation. This data prefixes each allocation.

Fields

private q{
        add!"bytesUsed"(result.length);
        add!"bytesAllocated"(result.length);
        immutable slack = this.goodAllocSize(result.length) - result.length;
        add!"bytesSlack"(slack);
        up!"numAllocate";
        add!"numAllocateOK"(result.length == bytes); // allocating 0 bytes is OK
        addPerCall!(f, n, "numAllocate", "numAllocateOK", "bytesAllocated")
            (1, result.length == bytes, result.length);
    } _updateStatsForAllocateResult

Methods

string define(string type, string[] names...)

void add(string counter)(Signed!size_t n)

void up(string counter)()

void down(string counter)()

private Ternary ownsImpl(string f = null, uint n = 0)(void[] b)

private void[] allocateImpl(string f = null, ulong n = 0)(size_t bytes)

private void[] alignedAllocateImpl(string f = null, ulong n = 0)(size_t bytes, uint a)

private bool expandImpl(string f = null, uint n = 0)(ref void[] b, size_t s)

private bool reallocateImpl(string f = null, uint n = 0)(ref void[] b, size_t s)

private bool deallocateImpl(string f = null, uint n = 0)(void[] b)

void reportStatistics(R)(auto ref R output)Reports per instance statistics to `output` (e.g. `stdout`). The format is simple: one kind and value per line, separated by a colon, e.g. `bytesAllocated:7395404`