Record

Counter values and intermediate counter deltas are stored as CounterTools.Records. This data structure can model the hierarchical layout of performance counters in a way that is not particularly mind-bending to deal with.

Working with CounterTools.Records is pretty easy. Records wrap either Tuples or Arrays, and have a name:

julia> using CounterTools

julia> record_1 = CounterTools.Record{:A}((1, 1))
A Record with 2 entries:
   Int64

A: (1, 1)

Records can be indexed:

julia> record_1[1]
1

Records can be nested

julia> record_2 = CounterTools.Record{:A}((1,2))
A Record with 2 entries:
   Int64

A: (1, 2)

julia> record = CounterTools.Record{:top}((record_1, record_2))
Top Record with 2 entries:
   A Record with 2 entries:
      Int64

Top:
   A: (1, 1)
   A: (1, 2)

Of course, nested records can be indexed as well

julia> record[2][2]
2

Records can be subtracted from one another The resulting Record has the same structure as the original records

julia> record - record
Top Record with 2 entries:
   A Record with 2 entries:
      Int64

Top:
   A: (0, 0)
   A: (0, 0)

All the leaf entries can be summed together using CounterTools.aggregate

julia> CounterTools.aggregate(record)
(2, 3)

If you want to apply a function to all of the leaf elements of a record, use CounterTools.mapleaves

julia> CounterTools.mapleaves(x -> 2x, record)
Top Record with 2 entries:
   A Record with 2 entries:
      Int64

Top:
   A: (2, 2)
   A: (2, 4)

Common Usage

Commonly, Records will be collected as a vector and the leaf elements of Records will be CounterTools.CounterValue. The easiest way to take counter differences and aggregate is use the following:

julia> records = [record for _ in 1:10];

julia> CounterTools.aggregate.(diff(records))
9-element Array{Tuple{Int64,Int64},1}:
 (0, 0)
 (0, 0)
 (0, 0)
 (0, 0)
 (0, 0)
 (0, 0)
 (0, 0)
 (0, 0)
 (0, 0)

Record Docstrings

CounterTools.Record — Type

Record{name}(data::T) where {T <: Union{Vector, NTuple}}

Create a named Record around data. The elements of data may themselves be Records, resulting in a hierarchical data structure.

source

CounterTools.aggregate — Function

aggregate(record::Record)
aggregate(f, record::Record)

Reduce over all the leaf (terminal) elements of record, applying f as the reduction function. If f is not supplied, it will defult to (x,y) -> x .+ y.

source

CounterTools.mapleaves — Function

mapleaves(f, record::Record) -> Record

Apply f to each leaf element of record. This will recursively descend through hierarchies of Records and only apply f to scalars.

The returned result will have the same hierarchical structure as record

source

CounterTools.CounterValue — Type

CounterValue(x::UInt)

A raw value returned from a performance counter. This type will automatically detect and correct for counter roll-over.

julia> a = CounterTools.CounterValue(0x0)
CV(0)

julia> b = CounterTools.CounterValue(0x1)
CV(1)

julia> b - a
1

julia> UInt(a - b)
0x00007fffffffffff

source