Overview

{governor} is a governor (or speed limiter) which limits the rate at which a for-loop or while-loop will run.

The total execution speed is limited by inserting short pauses based upon the time to run through the loop. The waiting time is adjusted continuously to meet the target duration.

Running a loop at a rate of 30 times/second

A common use for {governor} will be timing animation at, say, 30 frames per second.

library(governor)

# Limit loop to 30 frames-per-second i.e. 1/30th of a second per frame.
gov <- gov_init(1/30); 

# Running the loop 30 times at 30 frames-per-second should take ~1 second
# The actual work in this loop only takes 0.3seconds (30 * 0.01)
# So `gov_wait()` will pause every loop to maintain the interval
system.time({
  for (i in 1:30) {
    Sys.sleep(0.01)  # Work done in loop
    gov_wait(gov)    # Compensate to keep interval loop time
  }
})
#>    user  system elapsed 
#>   0.002   0.001   1.044

Skipping frames

When the actual work in the loop is fast, {governor} can compensate by waiting a longer amount of time.

When the work in the loop is slow, then {governor} can advise that the work for the next frame be skipped.

In this example, we want the loop to run at 30 frames per second (i.e. an interval of 0.033 seconds), but the work itself takes 0.04 seconds. The return value of gov_wait() is a logical value indicating whether it is recommended that the next frame is skipped in order to achieve the desired loop interval.

In the output from this code, the skip variable is printed to show that gov_wait() is advising that many frames should be skipped.

library(governor)

# Run loop at 30fps if possible
# Set a high learning rate so it will converge quickly
gov <- gov_init(1/30); 

# Running the loop 30 times at 30 frames-per-second should take ~1 second
# The actual work should take a total of 0.1 * 30 = 3 seconds!
system.time({
  skip <- FALSE
  for (i in 1:30) {
    if (!skip) {
      Sys.sleep(0.1)  # Work done in loop
    }
    skip <- gov_wait(gov)    # Compensate to keep interval loop time
    cat(skip, "\n")
  }
})
#> FALSE 
#> FALSE 
#> TRUE 
#> TRUE 
#> FALSE 
#> TRUE 
#> TRUE 
#> TRUE 
#> FALSE 
#> TRUE 
#> FALSE 
#> TRUE 
#> TRUE 
#> TRUE 
#> FALSE 
#> TRUE 
#> TRUE 
#> FALSE 
#> TRUE 
#> TRUE 
#> FALSE 
#> TRUE 
#> TRUE 
#> FALSE 
#> TRUE 
#> TRUE 
#> FALSE 
#> TRUE 
#> TRUE 
#> TRUE
#>    user  system elapsed 
#>   0.003   0.000   1.186

Setting timers

Timers are like alarm clocks that will return TRUE when the given duration has elapsed.

After returning TRUE, the timer will reset internally such that they will trigger again after another period has elapsed.

long_timer  <- timer_init(1)
short_timer <- timer_init(0.1)
counter <- 0L
while(TRUE) {
  if (timer_check(long_timer)) {
    cat("\nLong  timer fired at count: ", counter, "\n")
    break;
  } 
  if (timer_check(short_timer)) {
    cat("Short timer fired at count: ", counter, "\n")
  } 
  counter <- counter + 1L
}
#> Short timer fired at count:  188517 
#> Short timer fired at count:  419048 
#> Short timer fired at count:  651168 
#> Short timer fired at count:  885742 
#> Short timer fired at count:  1118751 
#> Short timer fired at count:  1347175 
#> Short timer fired at count:  1576178 
#> Short timer fired at count:  1808736 
#> Short timer fired at count:  2042220 
#> 
#> Long  timer fired at count:  2270863