ocean.math.Distribution

Helper class useful for producing apache bench style output about value distributions. For example:

Time distribution of 10000 requests:
 50.0% <= 234μs
 66.0% <= 413μs
 75.0% <= 498μs
 80.0% <= 575μs
 90.0% <= 754μs
 95.0% <= 787μs
 98.0% <= 943μs
 99.0% <= 1054μs
 99.5% <= 1183μs
 99.9% <= 7755μs
100.0% <= 8807μs (longest request)

146 requests (1.5%) took longer than 1000μs

Performance note: the lessThanCount(), greaterThanCount() and percentValue() methods all sort the list of values stored in the Distribution instance. In general it is thus best to add all the values you're interested in, then call the results methods, so the list only needs to be sorted once.

Usage example:

import ocean.math.Distribution;

import ocean.io.Stdout;

import ocean.time.StopWatch;

// Stopwatch instance.
StopWatch sw;

// Create a distribution instance initialised to contain 10_000 values.
// (The size can be extended, but it's set initially for the sake of
// pre-allocation.)
const num_requests = 10_000;
auto dist = new Distribution!(ulong)(num_requests);

// Perform a series of imaginary requests, timing each one and adding
// the time value to the distribution
for ( int i; i < num_requests; i++ )
{
    sw.start;
    doRequest();
    auto time = sw.microsec;

    dist ~= time;
}

// Display the times taken by 50%, 66% etc of the requests.
// (This produces output like apache bench.)
const percentages = [0.5, 0.66, 0.75, 0.8, 0.9, 0.95, 0.98, 0.99, 0.995, 0.999, 1];

foreach ( i, percentage; percentages )
{
    auto value = dist.percentValue(percentage);

    Stdout.formatln("{,5:1}% <= {}μs", percentage * 100, value);
}

// Display the number of requests which took longer than 1ms.
const timeout = 1_000; // 1ms
auto timed_out = dist.greaterThanCount(timeout);

Stdout.formatln("{} requests ({,3:1}%) took longer than {}μs",
        timed_out,
        (cast(float)timed_out / cast(float)dist.length) * 100.0,
        timeout);

// Clear distribution ready for next test.
dist.clear;