Data

Tools

Indexes

Applications

Experiments

Open Source Science

later

Schedule an R function or formula to run after a specified period of time

https://github.com/r-lib/later

Science Score: 26.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ○
    Committers with academic emails
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (15.7%) to scientific vocabulary

Keywords

event-loop r

Keywords from Contributors

visualisation unit-testing web-development web-app shiny latex rmarkdown setup teaching interactive
Last synced: 10 months ago · JSON representation

Repository

Schedule an R function or formula to run after a specified period of time

Basic Info
  • Host: GitHub
  • Owner: r-lib
  • License: other
  • Language: C++
  • Default Branch: main
  • Homepage: https://later.r-lib.org/
  • Size: 1.92 MB
Statistics
  • Stars: 147
  • Watchers: 6
  • Forks: 29
  • Open Issues: 24
  • Releases: 18
Topics
event-loop r
Created over 9 years ago · Last pushed 10 months ago
Metadata Files
Readme Changelog License Code of conduct

README.Rmd 

---
output: github_document
---



```{r}
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# later


[![R-CMD-check](https://github.com/r-lib/later/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/later/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/r-lib/later/graph/badge.svg)](https://app.codecov.io/gh/r-lib/later)


Schedule an R function or formula to run after a specified period of time. Similar to JavaScript's `setTimeout` function. Like JavaScript, R is single-threaded so there's no guarantee that the operation will run exactly at the requested time, only that at least that much time will elapse.

To avoid bugs due to reentrancy, by default, scheduled operations only run when there is no other R code present on the execution stack; i.e., when R is sitting at the top-level prompt. You can force past-due operations to run at a time of your choosing by calling `later::run_now()`.

The mechanism used by this package is inspired by Simon Urbanek's [background](https://github.com/s-u/background) package and similar code in Rhttpd.

## Installation

You can install the development version of later with:

``` r
pak::pak("r-lib/later")
```

## Usage from R

Pass a function (in this case, delayed by 5 seconds):

```r
later::later(\() print("Got here!"), 5)
```

Or a formula (in this case, run as soon as control returns to the top-level):

```r
later::later(~print("Got here!"))
```
### File Descriptor Readiness

It is also possible to have a function run based on when file descriptors are ready for reading or writing, at some indeterminate time in the future.

Below, a logical vector is printed indicating which of file descriptors 21 or 22 were ready, subject to a timeout of 1s.

```r
later::later_fd(\(x) print(x), c(21L, 22L), timeout = 1)
```

This is useful in particular for asynchronous I/O, allowing reads to be made from TCP sockets as soon as data becomes available. Functions such as `curl::multi_fdset()` return the relevant file descriptors to be monitored.

## Usage from C++

You can also call `later::later` from C++ code in your own packages, to cause your own C-style functions to be called back. This is safe to call from either the main R thread or a different thread; in both cases, your callback will be invoked from the main R thread.

`later::later` is accessible from `later_api.h` and its prototype looks like this:

```cpp
void later(void (*func)(void*), void* data, double secs)
```

The first argument is a pointer to a function that takes one `void*` argument and returns void. The second argument is a `void*` that will be passed to the function when it's called back. And the third argument is the number of seconds to wait (at a minimum) before invoking.

`later::later_fd` is also accessible from `later_api.h` and its prototype looks like this:

```cpp
void later_fd(void (*func)(int *, void *), void *data, int num_fds, struct pollfd *fds, double secs)
```
The first argument is a pointer to a function that takes two arguments: the first being an `int*` array provided by `later_fd()` when called back, and the second being a `void*`. The `int*` array will be the length of `num_fds` and contain the values `0`, `1` or `NA_INTEGER` to indicate the readiness of each file descriptor, or an error condition respectively. The second argument `data` is passed to the `void*` argument of the function when it's called back. The other required arguments are the total number of file descriptors, a pointer to an array of `stuct pollfd`, and the number of seconds to wait until timing out.

To use the C++ interface, you'll need to add `later` to your `DESCRIPTION` file under both `LinkingTo` and `Imports`, and also make sure that your `NAMESPACE` file has an `import(later)` entry.

### Background tasks

Finally, this package also offers a higher-level C++ helper class to make it easier to execute tasks on a background thread. It is also available from `later_api.h` and its public/protected interface looks like this:

```cpp
class BackgroundTask {

public:
  BackgroundTask();
  virtual ~BackgroundTask();

  // Start executing the task
  void begin();

protected:
  // The task to be executed on the background thread.
  // Neither the R runtime nor any R data structures may be
  // touched from the background thread; any values that need
  // to be passed into or out of the Execute method must be
  // included as fields on the Task subclass object.
  virtual void execute() = 0;

  // A short task that runs on the main R thread after the
  // background task has completed. It's safe to access the
  // R runtime and R data structures from here.
  virtual void complete() = 0;
}
```

Create your own subclass, implementing a custom constructor plus the `execute` and `complete` methods.

It's critical that the code in your `execute` method not mutate any R data structures, call any R code, or cause any R allocations, as it will execute in a background thread where such operations are unsafe. You can, however, perform such operations in the constructor (assuming you perform construction only from the main R thread) and `complete` method. Pass values between the constructor and methods using fields.

```rcpp
#include 
#include 

class MyTask : public later::BackgroundTask {
public:
  MyTask(Rcpp::NumericVector vec) :
    inputVals(Rcpp::as >(vec)) {
  }

protected:
  void execute() {
    double sum = 0;
    for (std::vector::const_iterator it = inputVals.begin();
      it != inputVals.end();
      it++) {

      sum += *it;
    }
    result = sum / inputVals.size();
  }

  void complete() {
    Rprintf("Result is %f\n", result);
  }

private:
  std::vector inputVals;
  double result;
};
```

To run the task, `new` up your subclass and call `begin()`, e.g. `(new MyTask(vec))->begin()`. There's no need to keep track of the pointer; the task object will delete itself when the task is complete.

```r
// [[Rcpp::export]]
void asyncMean(Rcpp::NumericVector data) {
  (new MyTask(data))->begin();
}
```

It's not very useful to execute tasks on background threads if you can't get access to the results back in R. The [promises](https://github.com/rstudio/promises) package complements later by providing a "promise" abstraction.

Owner

  • Name: R infrastructure
  • Login: r-lib
  • Kind: organization

GitHub Events

Total
  • Create event: 22
  • Release event: 4
  • Issues event: 35
  • Watch event: 8
  • Delete event: 14
  • Member event: 1
  • Issue comment event: 74
  • Push event: 129
  • Pull request review comment event: 90
  • Pull request review event: 95
  • Pull request event: 50
  • Fork event: 2
Last Year
  • Create event: 22
  • Release event: 4
  • Issues event: 35
  • Watch event: 8
  • Delete event: 14
  • Member event: 1
  • Issue comment event: 74
  • Push event: 129
  • Pull request review comment event: 90
  • Pull request review event: 95
  • Pull request event: 50
  • Fork event: 2

Committers

Last synced: 12 months ago

All Time
  • Total Commits: 305
  • Total Committers: 10
  • Avg Commits per committer: 30.5
  • Development Distribution Score (DDS): 0.449
Past Year
  • Commits: 18
  • Committers: 2
  • Avg Commits per committer: 9.0
  • Development Distribution Score (DDS): 0.5
Top Committers
Name Email Commits
Winston Chang w****n@s****g 168
Joe Cheng j****e@r****m 106
shikokuchuo 5****o 16
Barret Schloerke s****e@g****m 5
Carson Sievert c****1@g****m 3
Michael Chirico c****m@g****m 2
Mara Averick m****k@g****m 2
Tracy Teal t****l@g****m 1
Ray Donnelly m****d@g****m 1
Jeroen Ooms j****s@g****m 1
Committer Domains (Top 20 + Academic)
google.com: 1 rstudio.com: 1 stdout.org: 1

Issues and Pull Requests

Last synced: 10 months ago

All Time
  • Total issues: 86
  • Total pull requests: 84
  • Average time to close issues: 11 months
  • Average time to close pull requests: 3 months
  • Total issue authors: 48
  • Total pull request authors: 15
  • Average comments per issue: 2.71
  • Average comments per pull request: 1.68
  • Merged pull requests: 58
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 16
  • Pull requests: 33
  • Average time to close issues: 4 days
  • Average time to close pull requests: 3 days
  • Issue authors: 5
  • Pull request authors: 2
  • Average comments per issue: 0.44
  • Average comments per pull request: 1.48
  • Merged pull requests: 24
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • wch (14)
  • jcheng5 (11)
  • shikokuchuo (9)
  • nx10 (3)
  • dselivanov (2)
  • dereckmezquita (2)
  • dipterix (2)
  • barracuda156 (2)
  • r2evans (2)
  • leechaowen (1)
  • Jiefei-Wang (1)
  • Elimaker-code (1)
  • lionel- (1)
  • QuLogic (1)
  • toomish (1)
Pull Request Authors
  • shikokuchuo (36)
  • wch (22)
  • jcheng5 (15)
  • schloerke (6)
  • MichaelChirico (3)
  • vtamara (2)
  • cpsievert (2)
  • r2evans (2)
  • tracykteal (1)
  • bearloga (1)
  • batpigandme (1)
  • danieldjewell (1)
  • atheriel (1)
  • jeroen (1)
  • ThePrez (1)
Top Labels
Issue Labels
upkeep (1)
Pull Request Labels

Packages

  • Total packages: 3
  • Total downloads:
    • cran 576,246 last-month
  • Total docker downloads: 57,677,297
  • Total dependent packages: 42
    (may contain duplicates)
  • Total dependent repositories: 166
    (may contain duplicates)
  • Total versions: 42
  • Total maintainers: 1
cran.r-project.org: later

Utilities for Scheduling Functions to Execute Later with Event Loops

  • Versions: 21
  • Dependent Packages: 32
  • Dependent Repositories: 131
  • Downloads: 576,246 Last month
  • Docker Downloads: 57,677,297
Rankings
Downloads: 0.5%
Dependent repos count: 1.8%
Dependent packages count: 2.5%
Forks count: 2.9%
Stargazers count: 3.1%
Average: 4.7%
Docker downloads count: 17.3%
Maintainers (1)
charlie.gao@posit.co
Last synced: 10 months ago
proxy.golang.org: github.com/r-lib/later
  • Versions: 15
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.5%
Average: 5.7%
Dependent repos count: 5.9%
Last synced: 10 months ago
conda-forge.org: r-later
  • Versions: 6
  • Dependent Packages: 10
  • Dependent Repositories: 35
Rankings
Dependent packages count: 5.9%
Dependent repos count: 6.1%
Average: 19.2%
Stargazers count: 30.5%
Forks count: 34.1%
Last synced: 10 months ago

Dependencies

DESCRIPTION cran
  • Rcpp >= 0.12.9 imports
  • rlang * imports
  • knitr * suggests
  • rmarkdown * suggests
  • testthat >= 2.1.0 suggests
.github/workflows/R-CMD-check.yaml actions