Automatic and Manual Return of the Timings

Jonathan Berrisch

2024-09-22

Assign a Custom Name to the Timings Object

If you want to give the dataframe a different name, you can pass that name to the constructor:

Rcpp::cppFunction('
double demo_rnorm()
{
 Rcpp::Timer timer("mytimes");
 timer.tic();
 double x = rnorm(1, 1)[0];
 timer.toc();
 return(x);
}',
  depends = "rcpptimer"
)

demo_rnorm()

## [1] -0.4000435

print(mytimes)

##        Microseconds SD    Min    Max Count
## tictoc       11.231  0 11.231 11.231     1

Manually Handling the Results

You may need to handle the resulting DataFrame yourself instead of letting rcpptimer write it to the global environment.

This issue consists of two elements:

• Turn off the autoreturn feature
• Handle the results yourself

First, to turn off autoreturn, set the autoreturn variable of your Timer instance to false. That will prevent the timer from writing the results to the global environment.

Rcpp::cppFunction('
double demo_rnorm()
{
 Rcpp::Timer timer;
 timer.autoreturn = false;
 timer.tic("rnorm");
 double x = rnorm(1, 1)[0];
 timer.toc("rnorm");
 return(x);
}',
  depends = "rcpptimer"
)

demo_rnorm()

## [1] 1.255317

print(ls())

## [1] "demo_rnorm"

Now, mem will not write to the global environment. However, you can still access the results through the timer’s .stop() method:

Rcpp::cppFunction('
DataFrame demo_rnorm()
{
 Rcpp::Timer timer;
 timer.autoreturn = false;
 timer.tic("rnorm");
 double x = rnorm(1, 1)[0];
 timer.toc("rnorm");
 DataFrame times = timer.stop();
 return(times);
}',
  depends = "rcpptimer"
)

demo_rnorm()

##       Microseconds SD   Min   Max Count
## rnorm        6.473  0 6.473 6.473     1

It is also possible to use .stop() and let rcpptimer pass the results automatically. In the above example, just set autoreturn to true (the default) or delete that line.

You can find instructions in vignette("advanced") if you want to access the raw timings data.

Considerations for package authors

As a package author, you should parameterize the auto-return feature so your users can decide whether they want the results to be passed to the global environment and what name should be assigned. Below is an example of how to do this.

Rcpp::cppFunction('
double demo_rnorm(bool return_timings = false,
 const char* timings_name = "times")
{
 Rcpp::Timer timer(timings_name);
 timer.autoreturn = return_timings;
 timer.tic("rnorm");
 double x = rnorm(1, 1)[0];
 timer.toc("rnorm");
 return(x);
}',
  depends = "rcpptimer"
)

demo_rnorm(return_timings = FALSE)

## [1] 0.9944287

ls()

## [1] "demo_rnorm"

demo_rnorm(return_timings = TRUE)

## [1] 1.621553

ls()

## [1] "demo_rnorm" "times"

demo_rnorm(return_timings = TRUE, timings_name = "my_times")

## [1] 2.148412

ls()

## [1] "demo_rnorm" "my_times"   "times"