add later_recurring

NAMESPACE

@@ -8,6 +8,7 @@ export(destroy_loop)
 export(exists_loop)
 export(global_loop)
 export(later)
+export(later_recurring)
 export(loop_empty)
 export(next_op_secs)
 export(run_now)

NEWS.md

@@ -1,5 +1,6 @@
 ## later 1.1.0.9000
 
+* Added `later_recurring`, allowing a function to recur in its 'later' loop until an iteration limit (if set) or explicit cancellation. PR #133
 
 ## later 1.1.0.1
 

R/is_false.R

@@ -0,0 +1 @@
+is_false <- function(x) is.logical(x) && length(x) == 1L && !is.na(x) && !x

R/later.R

@@ -70,7 +70,7 @@ create_loop <- function(parent = current_loop(), autorun = NULL) {
     # This is for backward compatibility, if `create_loop(autorun=FALSE)` is called.
     parent <- NULL
   }
-  if (identical(parent, FALSE)) {
+  if (is_false(parent)) {
     # This is for backward compatibility, if `create_loop(FALSE)` is called.
     # (Previously the first and only parameter was `autorun`.)
     parent <- NULL

R/later_recurring.R

@@ -0,0 +1,37 @@
+#' @describeIn later Schedules a recurring task
+#' @details
+#'
+#' In `later_recurring`, if `func` returns an explicit `FALSE` then
+#' this is interpreted as self-cancelling the loop. Anything else
+#' returned (including multiple `FALSE`) is ignored.
+#' 
+#' @param limit Number of times to repeat the function. If `Inf` (the
+#'   default) then no limit.
+#' @examples
+#' # Limit number of executions to 3 times
+#' later_recurring(~ message("Hello from the past"), 1, limit = 3)
+#' 
+#' # Stop recurring when the return value is `FALSE`
+#' later_recurring(function() {
+#'   message("Flipping a coin to see if we run again...")
+#'   sample(c(TRUE, FALSE), size = 1L)
+#' }, 0.25, limit = Inf)
+#' @export
+later_recurring <- function(func, delay, limit = Inf, loop = current_loop()) {
+  func <- rlang::as_function(func)
+  cancelled <- FALSE
+  if (is.na(limit) || limit < 1)
+    stop("'limit' must be a positive number")
+  func2 <- function() {
+    limit <<- limit - 1L
+    ret <- func()
+    if (is_false(ret)) cancelled <<- TRUE
+    if (!cancelled && limit > 0)
+      handle <<- later(func2, delay, loop)
+  }
+  handle <- later(func2, delay, loop)
+  invisible(function() {
+    cancelled <<- TRUE
+    handle()
+  })
+}

tests/testthat/test-recurring.R

@@ -0,0 +1,27 @@
+context("test-recurring")
+
+test_that("Limited recurrence", {
+  # Repeat until the limit reached, stopped by limit
+  x <- 0
+  later_recurring(function() { x <<- x + 1 }, delay = 0.5, limit = 2)
+  run_now(0.5)
+  expect_identical(x, 1)
+  run_now(0.5)
+  expect_identical(x, 2)
+  run_now(1)
+  expect_identical(x, 2)
+})
+
+test_that("Self-cancelling recurrence", {
+  # Repeat until the function returns FALSE, self-cancelling
+  x <- 0
+  cancel <- later_recurring(function() { x <<- x + 1; (x < 2) }, delay = 0.5, limit = 4)
+  expect_identical(length(list_queue()), 1L)
+  run_now(0.5)
+  expect_identical(x, 1)
+  run_now(0.5)
+  expect_identical(x, 2)
+  run_now(1)
+  expect_identical(x, 2)
+  expect_identical(length(list_queue()), 0L)
+})