Automatic and Manual Return of the Timings

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] 1.156661

print(mytimes)

##        Microseconds SD   Min   Max Count
## tictoc        5.962  0 5.962 5.962     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] -0.01127144

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         5.73  0 5.73 5.73     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.554856

ls()

## [1] "demo_rnorm"

demo_rnorm(return_timings = TRUE)

## [1] 2.637555

ls()

## [1] "demo_rnorm" "times"

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

## [1] 0.9441437

ls()

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