A Short Introduction to rcpptimer

This package provides a simple timer for Rcpp code. The interface resembles the tictoc R package. The package wraps cpptimer, a header-only library that contains a class called CppTimer. rcpptimer adds this class as Timer to the Rcpp namespace.

This introduction explains how to use Rcpp::Timer with Rcpp::cppFunction and how:

You can use multiple (potentially nested) timers
You can time scopes using Rcpp::Timer::ScopedTimer
You can turn off Warnings

Check out the other vignettes for:

Using rcpptimer together with Rcpp::sourceCpp vignette("sourceCpp")
Adding rcpptimer to a Package vignette("packages")
Automatic and Manual Return of the Timings vignette("autoreturn")
Accessing unprocessed Timings, Resetting and Updating the Timer Results vignette("advanced")

Initialize a Timer

Initializing a timer is simple. There are four constructors available. The default constructor initializes a timer with warnings enabled that will write the results as data.frame called “times” to the R environment:

Rcpp::Timer timer; // default constructor
Rcpp::Timer timer("my_timer"); // Set a custom name for the results
Rcpp::Timer timer(false); // Disable warnings
Rcpp::Timer timer("my_timer", false); // Set a custom name and disable warnings

Below and throughout other vignettes, we will use all four as needed.

Straightforward Example

With Rcpp::cppFunction, we must add the depends argument to the function to tell the compiler we want to link the ‘rcpptimer’ library to the C++ code. Then, we can construct an instance of the Timer class and use the tic and toc methods to measure the time it takes to execute a code block. Here, we allocate some memory to have something to measure:

Rcpp::cppFunction("
double add(double &x, double &y)
{
 Rcpp::Timer timer;
 timer.tic();
 double z = x + y;
 timer.toc();
 return(z);
}",
  depends = "rcpptimer"
)

add(rnorm(1), runif(1))
#> [1] 1.441275

This function will automatically write a data frame called “times” to the R environment. Read more about that autoreturn feature (i.e., how to assign a custom variable name and how to manually handle the results) in vignette("autoreturn").

The resulting times object has two classes: data.frame and rcpptimer. We provide a custom S3 method for printing the results. If it is registered, it may scale the results to improve readability (see rcpptimer::print.rcpptimer). Otherwise, it will print the results using base::print.data.frame.

print(times)
#>        Microseconds SD   Min   Max Count
#> tictoc        1.373  0 1.373 1.373     1

Multiple Timers

You can also use multiple timers in the same function. The Timers can be nested and overlapping. Just pass a string to the tic and toc methods to distinguish the timers:

Rcpp::cppFunction('
double add(double &x, double &y)
{
 Rcpp::Timer timer;
 timer.tic("body");
 timer.tic("add_1");
 timer.tic("add_2");
 double z = x + y;
 timer.toc("add_1");
 timer.toc("add_2");
 timer.toc("body");
 return(z);
}',
  depends = "rcpptimer"
)

add(rnorm(1), runif(1))
#> [1] 0.03072276

print(times)
#>       Microseconds SD   Min   Max Count
#> add_1        1.253  0 1.253 1.253     1
#> add_2        0.932  0 0.932 0.932     1
#> body         3.377  0 3.377 3.377     1

rcpptimer will group multiple timers with the same name and calculate summary statistics for them. Consider this more advanced example, which also uses OpenMP:

// fibonacci.cpp
std::vector<long int> fibonacci_omp(std::vector<long int> n)
{

  Rcpp::Timer timer;

  // This scoped timer measures the total execution time of 'fibonacci'
  Rcpp::Timer::ScopedTimer scpdtmr(timer, "fib_body");

  std::vector<long int> results = n;

#pragma omp parallel for
  for (unsigned int i = 0; i < n.size(); ++i)
  {
    timer.tic("fib_" + std::to_string(n[i]));
    results[i] = fib(n[i]);
    timer.toc("fib_" + std::to_string(n[i]));
  }

  return (results);
}

This function is included in rcpptimer, so we can execute it right away:

results <- rcpptimer::fibonacci_omp(n = rep(20:25, 10))
print(times)
#>          Microseconds     SD      Min      Max Count
#> fib_20         37.034 14.515   27.893   72.887    10
#> fib_21         41.228  7.014   37.450   54.653    10
#> fib_22         81.422 21.345   70.603  122.200    10
#> fib_23        122.662 27.158   97.904  164.790    10
#> fib_24        213.811 40.340  175.200  260.270    10
#> fib_25        289.877 47.224  252.535  368.583    10
#> fib_body     2682.117  0.000 2682.117 2682.117     1

Timing Scopes with Rcpp::Timer::ScopedTimer

The ScopedTimer lets you measure the execution time of scopes. It will call ..tic() upon creation and .toc() upon destruction. Consider the simple example below:

Rcpp::cppFunction('
double add(double &x, double &y)
{
 Rcpp::Timer timer;
 Rcpp::Timer::ScopedTimer scoped_timer(timer, "add");
 double z = x + y;
 return(z);
}',
  depends = "rcpptimer"
)

add(rnorm(1), runif(1))
#> [1] 0.03174557

print(times)
#>     Microseconds SD   Min   Max Count
#> add        1.272  0 1.272 1.272     1

Note that you only need to initialize the ScopedTimer. Once it goes out of scope, the timer will automatically be stopped.

Warnings and how to Disable them

The default setting will warn about timers that have been started using .tic but never stopped using .toc() and vice versa. This is useful to catch unmatched .tic() and .toc() calls that may be unmatched due to missing statements or typos.

For example, the following code will produce two warnings:

Rcpp::cppFunction('
double add(double &x, double &y)
{
 Rcpp::Timer timer;
 Rcpp::Timer::ScopedTimer scoped_timer(timer, "add");
 timer.tic("add");
 double z = x + y;
 timer.toc("ad");
 return(z);
}',
  depends = "rcpptimer"
)

add(rnorm(1), runif(1))
#> Warning in add(rnorm(1), runif(1)): Timer "ad" not started yet. 
#> Use tic("ad") to start the timer.
#> [1] 0.6037769

Note that this does not affect terminated timers such as ‘mem’.

print(times)
#>     Nanoseconds SD Min Max Count
#> add         812  0 812 812     1

These warnings occur at runtime. Unfortunately, we can’t check for this at compile time.

However, you can turn off these warnings by passing false to the constructor. This is useful if you need .toc() calls in code blocks that may not get executed, e.g. in conditional statements. The example below will not produce any warnings:

Rcpp::cppFunction('
double add(double &x, double &y)
{
 Rcpp::Timer timer(false);
 Rcpp::Timer::ScopedTimer scoped_timer(timer, "add");
 timer.tic("add");
 double z = x + y;
 timer.toc("ad");
 return(z);
}',
  depends = "rcpptimer"
)

add(rnorm(1), runif(1))
#> [1] 1.170757

print(times)
#>     Nanoseconds SD Min Max Count
#> add         711  0 711 711     1