Profiling

The profiling/ directory hosts utilities for measuring and profiling cdough’s performance.

Contents:

stopwatch.h – Lightweight wall-clock timer.
memory.h – Memory checkpoints for the current process (current/peak resident set size) with stopwatch-like output.
thread_profiling.h – Thread-local CPU usage and timing utilities.
output.h – Storage and formatting of key-value benchmark outputs.
utils.h – Miscellaneous helpers shared across benchmarks.

Defines

LABEL_WIDTH

STOPWATCH_PREC

namespace cdough

namespace benchmarking

namespace stopwatch

Typedefs

using sec = std::chrono::duration<float, std::chrono::seconds::period>

Functions

static inline void _validate_label_no_quotes(const std::string &label)

Validate that labels do not contain quotation marks (single and double).

Parameters:: label – The string label to validate.

void timepoint(std::string label)

Mark a timepoint with the given label and output the elapsed time on Party 0. If this is the first time timepoint has been called, just print the label, and start the clock. Otherwise, outut the time since the last timepoint.

Parameters:: label –

double get_elapsed()

Get the elapsed time without printing. Still registers intervals in the manner of timepoint. This means that interleaved calls to timepoint and get_elapsed will return the time elapsed since either was last called.

Returns:: float

void to_json(): Write aggregated profile results to .experiment.json. Includes both stopwatch timing results and general benchmark outputs.

void done()

Output the time elapsed since the first call to timepoint or get_elapsed. This is useful to call at the end of a program to see how long the entire execution takes.

done can be called multiple times; it will always output the elapsed time since the same initial timepoint.

void profile_init()

Initialized the profiler.

cdough provides a primitive profiling utility based on the stopwatch which simply aggregates elapsed times registered under each label. The profiler should not be used when high-accuracy measurements are needed, but it is sufficient for simple tests and benchmarks.

void profile_timepoint(std::string label)

Register a profile timepoint under label. Semantics are similar to timepoint, but nothing is printed.

Parameters:: label –

void profile_preprocessing(std::optional<std::string> label = {})

Register a preprocessing timepoint with an optional label. If no label is provided, update the last timepoint but do not measure the elapsed time. If a label is provided, measure the elapsed time for both this label and the special PREPROCESSING symbol.

Parameters:: label –

void profile_comm(std::string label, double t)

Register a given interval for the given communication category. This function behaves differently due to architectural differences in measuring compute versus communication, but (TODO) should probably be updated.

Parameters:

label –
t – time in seconds

void profile_done(): Complete profiling and output a profiling report. Prints each category of aggregated times and separates out preprocessing. Also prints out a breakdown of offline versus online time.

Variables

int partyID = 0

std::chrono::steady_clock::time_point _tp_first

static std::map<std::string, double> stopwatch_times

static std::map<std::string, double> profile_times

static std::map<std::string, double> preproc_times

static std::map<std::string, double> comm_times

static std::chrono::steady_clock::time_point profile_last

static std::chrono::steady_clock::time_point preproc_last

Stopwatch-like memory checkpoints for the current process.

Utilities to query current and peak resident set size (RSS) and a mempoint(label) helper that prints formatted checkpoints. Output is restricted to Party 0 for consistency with the stopwatch utilities. All values are displayed in MiB/GiB using 1024-based units.

Platform notes:

Linux: reads /proc/self/status (VmRSS for current RSS, VmHWM for peak RSS) for accurate values.
Other OS: falls back to getrusage; often only peak RSS is available.

Party gating:

This header aliases cdough::benchmarking::stopwatch::partyID, so existing runtime/communicator initialization automatically controls whether memory checkpoints print (Party 0 only).

Example:

#include "profiling/memory.h"
cdough::benchmarking::memory::mempoint("Start");
// ... workload that allocates memory ...
cdough::benchmarking::memory::mempoint("After Load");

namespace cdough

namespace benchmarking

namespace memory

Functions

inline double bytes_to_mib(long long bytes) noexcept

Convert bytes to MiB.

Parameters:: bytes – The number of bytes to convert.
Returns:: The number of MiB.

static size_t read_value_kb_from_proc_status(const char *key) noexcept

Read a kB-valued field from /proc/self/status.

Parses the first line whose prefix matches the provided key and returns the numeric value (in kilobytes) as reported by the kernel.

Parameters:: key – The field name prefix to search for (e.g., “VmRSS:” or “VmHWM:”).
Returns:: size_t The parsed value in kilobytes, or 0 if not found or on error.

size_t get_rss_bytes() noexcept: Returns current Resident Set Size (RSS) in bytes.

size_t get_peak_rss_bytes() noexcept: Returns peak Resident Set Size (high-water mark) in bytes.

void mempoint(const std::string &label)

Prints a memory checkpoint with label, showing current RSS, delta since last checkpoint, and peak RSS. Mirrors stopwatch-style formatting.

Parameters:: label – The label to print.

Variables

static int &partyID = cdough::benchmarking::stopwatch::partyID 

double kBytesPerMiB = 1024.0 * 1024.0

Defines

HOST_NAME_MAX

Functions

std::string exec(const char *cmd)

Execute the command cmd and return its output.

Parameters:: cmd – command to run
Returns:: std::string stdout from the command

std::string prependHash(const std::string &str)

Prepend a hash (#) to each line on the input str and return the new string. Does not modify its input.

Parameters:: str –
Returns:: std::string

std::string hostname()

Get the hostname of this machine. Returns only the first HOST_NAME_MAX characters of the host name. This value defaults to 256 but can be increased with a compile-time define.

Returns:: std::string

namespace cdough

namespace instrumentation

namespace thread_stopwatch

Functions

uint64_t get_now_ns()

Get the current time of steady_clock in nanoseconds.

Returns:: uint64_t

double get_aggregate_comm(int pid = 0)

Return the sum of all measured timing events. TODO: this is incorrectly named; does not apply only to communication.

Parameters:: pid –
Returns:: double

void init_map(std::thread::id tid)

Initialize the timing map for thread id tid.

Parameters:: tid –

Variables

std::map<int64_t, std::atomic_uint64_t> timing

Map from thread ID to timing information. Switching to atomic u64 for communication timing purposes only.

TODO: revert this to fix write

class InstrumentBlock

#include <thread_profiling.h>

A utility class to measure the time taken in a given C++ code block. Instantiate a named instance of this class at, or near, the start of a block. The constructor of this class will record the current time, and the destructor (which fires when the block completes) computes the elapsed time and stores it in the timing map. InstrumentBlock records the time between its construction and the end of the block. Thus it need not time an entire block.

The string meta passed in the constructor labels a block. This information is saved to the output file and can be used by later analysis scripts.

It may be possible to use InstrumentBlock in other, non-block, contexts, by taking advantage of C++ scoping rules. This behavior has not been tested.

WARNING: without an object name, the compiler will immediately destroy the object, and no timing information will be available. That is,

InstrumentBlock _ib{"wait"}

works, but

InstrumentBlock{"wait"}

will not.

Public Functions

template<typename ...T> inline InstrumentBlock(T... args)

Default constructor when INSTRUMENT_THREADS is not defined. This constructor is provided so that cdough can be compiled without thread profiling, but without having to remove InstrumentBlocks sprinkled throughout the codebase. When profiling is turned off, the constructor does nothing and we use the default destructor.

Template Parameters:: T –
Parameters:: args –

Private Members

const int64_t tid

const uint64_t start

uint64_t end

const std::string meta

namespace cdough

namespace benchmarking

Functions

template<typename T> void output(const std::string &key, const T &value)

inline void clear_outputs(): Clear all general outputs. Useful for resetting between runs.

inline void write_outputs_to_json(std::ostream &out, bool &first)

Write general outputs to JSON stream. Used by stopwatch::to_json().

Parameters:

out – Output stream to write to
first – Reference to boolean tracking if this is the first entry

Variables

std::map<std::string, std::variant<double, int64_t>> general_outputs

namespace stopwatch

Defines

PROFILE(EXPR, NAME)

Typedefs

using sec = std::chrono::duration<float, std::chrono::seconds::period>

namespace cdough

namespace benchmarking

namespace utils

Functions

static void print_bin(int num1, int num2, bool add_line)

template<typename... T> static void timeTest (void(func)(T...), std::string name, int batch_nums, int size, T... args)

template<typename T> static int duration_to_ms(std::chrono::time_point<T> a, std::chrono::time_point<T> b)