DeltaT – A Header-Only C++ Library for Measuring Execution Time

DeltaT (short for Delta Time) is a lightweight, header-only C++ library designed for accurate measurement of function execution time. It is especially useful for benchmarking small, fast functions with sub-millisecond precision.

🌟 Features

• Header-only: Just include and use — no linking required.
• Template-friendly: Works seamlessly with templated and overloaded functions.
• Precise timing: Measures execution time with a resolution down to ~0.5ms (suitable for short functions).
• Easy to use: Simple API with configurable repetition count for statistical accuracy.
• Statistical metrics: Provides mean, standard deviation, min, max, and total execution time.

📦 Installation

DeltaT is a header-only library. You can integrate it into your project using several methods:

Using CMake FetchContent (Recommended)

include(FetchContent)

FetchContent_Declare(
  deltat
  GIT_REPOSITORY https://github.com/jzcurious/deltat.git
  GIT_TAG        v1.0.0  # Use the latest release tag
)

FetchContent_MakeAvailable(deltat)

# Link the library to your target
target_link_libraries(your_target PRIVATE deltat)

Using CPM (CMake Package Manager)

First, install CPM if you haven't already, then:

CPMAddPackage(
  NAME deltat
  GITHUB_REPOSITORY jzcurious/deltat
  GIT_TAG v1.0.0  # Use the latest release tag
)

# Link the library to your target
target_link_libraries(your_target PRIVATE deltat::deltat)

Manual Installation

Alternatively, you can manually copy the deltat folder into your project and include it:

#include "deltat/timeit.hpp"

No additional linking is required for header-only usage.

🧪 Example Usage

#include "deltat/timeit.hpp"
#include <iostream>

template <class... Ts>
double sum(Ts... args) {
  return (... + args);
}

int main() {
  dt::TimeIt ti(sum<int, int, float, double, short>, {.nrepetitions = 100});

  ti.run(1, 2, 3, 4, 5);
  ti.run(5, 4, 3, 2, 1);

  std::cout << ti.metrics() << std::endl;
  return 0;
}

Output

metrics_t{num=200, total=2.334e-07, mean=1.167e-09, std=4.91082e-09, min=-2.953e-09, max=8.047e-09}

📊 Metrics Explained

Each metrics_t object contains:

• num: Total number of measured executions.
• total: Total time taken across all executions (in seconds).
• mean: Average execution time (in seconds).
• std: Standard deviation of execution times.
• min: Minimum measured time.
• max: Maximum measured time.

⚠️ Note: Negative min values may appear due to clock resolution and system overhead.

⚙️ Accuracy

DeltaT is optimized for measuring short durations and provides a timing resolution of up to ~0.5 milliseconds. This makes it ideal for benchmarking lightweight functions.

⚙️ Custom Timers

DeltaT supports custom timer implementations. To create your own timer, define a class that satisfies the TimerKind concept:

template <class T>
concept TimerKind = requires(T x) {
  { x.start() } -> std::same_as<void>;
  { x.stop() } -> std::same_as<void>;
  { x.elapsed() } -> std::same_as<double>;
};

Example Custom Timer

class MyHighResTimer {
private:
  std::chrono::high_resolution_clock::time_point start_time;
  std::chrono::high_resolution_clock::time_point end_time;

public:
  void start() {
    start_time = std::chrono::high_resolution_clock::now();
  }

  void stop() {
    end_time = std::chrono::high_resolution_clock::now();
  }

  double elapsed() {
    auto duration = std::chrono::duration_cast<std::chrono::nanoseconds>(end_time - start_time);
    return duration.count() * 1e-9; // Convert to seconds
  }
};

// Usage with TimeIt
dt::TimeIt ti(my_function, {.nrepetitions = 1000}, MyHighResTimer{});

This allows you to use platform-specific high-resolution timers or specialized timing mechanisms for even more precise measurements.

📄 License

This project is licensed under the GNU General Public License. See the LICENSE file for details.