Library Reference

version 2.111.0

Internal API

If you spot a problem with this page, click here to create a Bugzilla issue.

Quickly fork, edit online, and submit a pull request for this page.Requires a signed-in GitHub account. This works well for small changes.If you'd like to make larger changes you may want to consider usinga local clone.

std.experimental.allocator.building_blocks.stats_collector

Allocator that collects useful statistics about allocations, both global and percalling point. The statistics collected can be configured statically by choosingcombinations ofOptions appropriately.

Sourcestd/experimental/allocator/building_blocks/stats_collector.d

Examples:

import std.experimental.allocator.gc_allocator : GCAllocator;import std.experimental.allocator.building_blocks.free_list : FreeList;alias Allocator = StatsCollector!(GCAllocator, Options.bytesUsed);

enumOptions: ulong;

Options forStatsCollector defined below. Each enables duringcompilation one specific counter, statistic, or other piece of information.

numOwns: Counts the number of calls toowns.
numAllocate: Counts the number of calls toallocate. All calls are counted, including requests for zero bytes or failed requests.
numAllocateOK: Counts the number of calls toallocate that succeeded, i.e. they returned a block as large as requested. (N.B. requests for zero bytes count as successful.)
numExpand: Counts the number of calls toexpand, regardless of arguments or result.
numExpandOK: Counts the number of calls toexpand that resulted in a successful expansion.
numReallocate: Counts the number of calls toreallocate, regardless of arguments or result.
numReallocateOK: Counts the number of calls toreallocate that succeeded. (Reallocations to zero bytes count as successful.)
numReallocateInPlace: Counts the number of calls toreallocate 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 finds room at the current block's end in a large fraction of the cases, but also that internal fragmentation may be high (the size of the unit of allocation is large compared to the typical allocation size of the application).
numDeallocate: Counts the number of calls todeallocate.
numDeallocateAll: Counts the number of calls todeallocateAll.
numAlignedAllocate: Counts the number of calls toalignedAllocate. All calls are counted, including requests for zero bytes or failed requests.
numAlignedAllocateOk: Counts the number of calls toalignedAllocate that succeeded, i.e. they returned a block as large as requested. (N.B. requests for zero bytes count as successful.)
numAll: Chooses allnumXxx flags.
bytesUsed: Tracks 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: Tracks total cumulative bytes allocated by means ofallocate,expand, andreallocate (when resulting in an expansion). This number always grows and indicates allocation traffic. To compute bytes deallocated cumulatively, subtractbytesUsed frombytesAllocated.
bytesExpanded: Tracks the sum of alldelta values in calls of the formexpand(b, delta) that succeed (returntrue).
bytesContracted: Tracks the sum of allb.length - s withb.length > s in calls of the formrealloc(b, s) that succeed (returntrue). In per-call statistics, also unambiguously counts the bytes deallocated withdeallocate.
bytesMoved: Tracks the sum of all bytes moved as a result of calls torealloc that were unable to reallocate in place. A large number (relative to bytesAllocated) indicates that the application should use larger preallocations.
bytesNotMoved: Tracks the sum of all bytes NOT moved as result of calls torealloc that managed to reallocate in place. A large number (relative to bytesAllocated) indicates that the application is expansion-intensive and is saving a good amount of moves. However, if this number is relatively small andbytesSlack is high, it means the application is overallocating for little benefit.
bytesSlack: Measures the sum of extra bytes allocated beyond the bytes requested, i.e. theinternal fragmentation. This is the current effective number of slack bytes, and it goes up and down with time.
bytesHighTide: Measures the maximum bytes allocated over the time. This is useful for dimensioning allocators.
bytesAll: Chooses allbyteXxx flags.
all: Combines all flags above.

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

Allocator that collects extra data about allocations. Since each piece ofinformation adds size and time overhead, statistics can be individually enabledor disabled through compile-timeflags.

All stats of the formnumXxx record counts of events occurring, such ascalls to functions and specific results. The stats of the formbytesXxxcollect cumulative sizes.

In addition, the datacallerSize,callerModule,callerFile,callerLine, andcallerTime is associated with each specific allocation.This data prefixes each allocation.

Examples:

import std.experimental.allocator.building_blocks.free_list : FreeList;import std.experimental.allocator.gc_allocator : GCAllocator;alias Allocator =StatsCollector!(GCAllocator, Options.all, Options.all);Allocator alloc;auto b = alloc.allocate(10);alloc.reallocate(b, 20);alloc.deallocate(b);import std.file : deleteme, remove;import std.range : walkLength;import std.stdio : File;auto f = deleteme ~"-dlang.std.experimental.allocator.stats_collector.txt";scope(exit) remove(f);Allocator.reportPerCallStatistics(File(f,"w"));alloc.reportStatistics(File(f,"a"));writeln(File(f).byLine.walkLength);// 24

Allocatorparent;

The parent allocator is publicly accessible either as a direct member if it holds state, or as an alias toAllocator.instance otherwise. One may use it for making calls that won't count toward statistics collection.

aliasalignment = Allocator.alignment;

Alignment offered is equal toAllocator.alignment.

Ternaryowns(void[]b);

IncrementsnumOwns (per instance and and per call) and forwards to parent.owns(b).

void[]allocate(size_tn);

Forwards toparent.allocate. Affects per instance:numAllocate,bytesUsed,bytesAllocated,bytesSlack,numAllocateOK, andbytesHighTide. Affects per call:numAllocate, numAllocateOK, andbytesAllocated.

void[]alignedAllocate(size_tn, uinta);

Forwards toparent.alignedAllocate. Affects per instance:numAlignedAllocate,bytesUsed,bytesAllocated,bytesSlack,numAlignedAllocateOk, andbytesHighTide. Affects per call:numAlignedAllocate,numAlignedAllocateOk, andbytesAllocated.

boolexpand(ref void[]b, size_tdelta);

Defined whether or notAllocator.expand is defined. Affects per instance:numExpand,numExpandOK,bytesExpanded,bytesSlack,bytesAllocated, andbytesUsed. Affects per call:numExpand,numExpandOK,bytesExpanded, andbytesAllocated.

boolreallocate(ref void[]b, size_ts);

Defined whether or notAllocator.reallocate is defined. Affects per instance:numReallocate,numReallocateOK, numReallocateInPlace,bytesNotMoved,bytesAllocated, bytesSlack,bytesExpanded, andbytesContracted. Affects per call:numReallocate,numReallocateOK,numReallocateInPlace,bytesNotMoved,bytesExpanded,bytesContracted, andbytesMoved.

booldeallocate(void[]b);

Defined whether or notAllocator.deallocate is defined. Affects per instance:numDeallocate,bytesUsed, andbytesSlack. Affects per call:numDeallocate andbytesContracted.

booldeallocateAll();

Defined only ifAllocator.deallocateAll is defined. Affects per instance and per callnumDeallocateAll.

pure nothrow @nogc @safe Ternaryempty();

Defined only ifOptions.bytesUsed is defined. ReturnsbytesUsed == 0.

voidreportStatistics(R)(auto ref Routput);

Reports per instance statistics tooutput (e.g.stdout). The format is simple: one kind and value per line, separated by a colon, e.g.bytesAllocated:7395404

structPerCallStatistics;

Defined ifperCallFlags is nonzero.

stringfile; uintline;: The file and line of the call.
Options[]opts;: The options corresponding to the statistics collected.
ulong[]values;: The values of the statistics. Has the same length asopts.
stringtoString() const;: Format to a string such as:mymodule.d(655): [numAllocate:21, numAllocateOK:21, bytesAllocated:324202].

static autobyFileLine();

Defined ifperCallFlags is nonzero. Iterates all monitored file/line instances. The order of iteration is not meaningful (items are inserted at the front of a list upon the first call), so preprocessing the statistics after collection might be appropriate.

voidreportPerCallStatistics(R)(auto ref Routput);

Defined ifperCallFlags is nonzero. Outputs (e.g. to aFile) a simple report of the collected per-call statistics.

Movatterモバイル変換

Library Reference

std.experimental.allocator.building_blocks.stats_collector