StatsCollector

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.

struct StatsCollector (

Allocator

ulong flags = Options.all

ulong perCallFlags = 0

) {

static if(stateSize!Allocator)

Allocator parent;

alias parent = Allocator.instance;

alias alignment = Allocator.alignment;

static if(__traits(hasMember, Allocator, "owns"))
static if((perCallFlags & Options.numOwns) == 0)

Ternary owns(void[] b);

static if(__traits(hasMember, Allocator, "owns"))
static if(!((perCallFlags & Options.numOwns) == 0))

Ternary owns(void[] b);

static if(!(perCallFlags & (Options.numAllocate | Options.numAllocateOK | Options.bytesAllocated)))

void[] allocate(size_t n);

static if(!(!(perCallFlags & (Options.numAllocate | Options.numAllocateOK | Options.bytesAllocated))))

void[] allocate(size_t bytes);

static if(!(perCallFlags & (Options.numExpand | Options.numExpandOK | Options.bytesExpanded)))

bool expand(void[] b, size_t delta);

static if(!(!(perCallFlags & (Options.numExpand | Options.numExpandOK | Options.bytesExpanded))))

bool expand(void[] b, size_t delta);

bool reallocate(void[] b, size_t s);

bool reallocate(void[] b, size_t s);

static if(!(perCallFlags & (Options.numDeallocate | Options.bytesContracted)))

bool deallocate(void[] b);

static if(!(!(perCallFlags & (Options.numDeallocate | Options.bytesContracted))))

bool deallocate(void[] b);

static if(__traits(hasMember, Allocator, "deallocateAll"))
static if(!(perCallFlags & Options.numDeallocateAll))

bool deallocateAll();

static if(__traits(hasMember, Allocator, "deallocateAll"))
static if(!(!(perCallFlags & Options.numDeallocateAll)))

bool deallocateAll();

static if(flags & Options.bytesUsed)

Ternary empty();

void reportStatistics(R output);

struct PerCallStatistics;

static if(perCallFlags)

static auto byFileLine();

static if(perCallFlags)

static void reportPerCallStatistics(R output);

}

Members

Aliases

alignment alias alignment = Allocator.alignment: Alignment offered is equal to Allocator.alignment.
parent alias parent = Allocator.instance: Undocumented in source.

Functions

allocate void[] allocate(size_t n): Forwards to parent.allocate. Affects per instance: numAllocate, bytesUsed, bytesAllocated, bytesSlack, numAllocateOK, and bytesHighTide. Affects per call: numAllocate, numAllocateOK, and bytesAllocated.
allocate void[] allocate(size_t bytes): Undocumented in source. Be warned that the author may not have intended to support it.
deallocate bool deallocate(void[] b): Defined whether or not Allocator.deallocate is defined. Affects per instance: numDeallocate, bytesUsed, and bytesSlack. Affects per call: numDeallocate and bytesContracted.
deallocate bool deallocate(void[] b): Undocumented in source. Be warned that the author may not have intended to support it.
deallocateAll bool deallocateAll(): Defined only if Allocator.deallocateAll is defined. Affects per instance and per call numDeallocateAll.
deallocateAll bool deallocateAll(): Undocumented in source. Be warned that the author may not have intended to support it.
empty Ternary empty(): Defined only if Options.bytesUsed is defined. Returns bytesUsed == 0.
expand bool expand(void[] b, size_t delta): Defined whether or not Allocator.expand is defined. Affects per instance: numExpand, numExpandOK, bytesExpanded, bytesSlack, bytesAllocated, and bytesUsed. Affects per call: numExpand, numExpandOK, bytesExpanded, and bytesAllocated.
expand bool expand(void[] b, size_t delta): Undocumented in source. Be warned that the author may not have intended to support it.
owns Ternary owns(void[] b): Undocumented in source. Be warned that the author may not have intended to support it.
owns Ternary owns(void[] b): Undocumented in source. Be warned that the author may not have intended to support it.
reallocate bool reallocate(void[] b, size_t s): Defined whether or not Allocator.reallocate is defined. Affects per instance: numReallocate, numReallocateOK, numReallocateInPlace, bytesNotMoved, bytesAllocated, bytesSlack, bytesExpanded, and bytesContracted. Affects per call: numReallocate, numReallocateOK, numReallocateInPlace, bytesNotMoved, bytesExpanded, bytesContracted, and bytesMoved.
reallocate bool reallocate(void[] b, size_t s): Undocumented in source. Be warned that the author may not have intended to support it.
reportStatistics void reportStatistics(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

Static functions

byFileLine auto byFileLine(): Defined if perCallFlags 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.
reportPerCallStatistics void reportPerCallStatistics(R output): Defined if perCallFlags is nonzero. Outputs (e.g. to a File) a simple report of the collected per-call statistics.

Structs

PerCallStatistics struct PerCallStatistics: Defined if perCallFlags is nonzero.

Variables

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

Examples

import stdx.allocator.building_blocks.free_list : FreeList;
import stdx.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);

static if (__VERSION__ >= 2073)
{
    import std.file : deleteme, remove;
    import std.range : walkLength;
    import std.stdio : File;

    auto f = deleteme ~ "-dlang.stdx.allocator.stats_collector.txt";
    scope(exit) remove(f);
    Allocator.reportPerCallStatistics(File(f, "w"));
    alloc.reportStatistics(File(f, "a"));
    assert(File(f).byLine.walkLength == 22);
}