> For the complete documentation index, see [llms.txt](https://hmdc.gitbook.io/r/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hmdc.gitbook.io/r/bestpractices/usingpromises.md).

# Using promises

As explained in [Limiting the number of R Threads](/r/config/numrthreads.md), R is single-threaded.

While our Shiny toolchain optimizes your application by running multiple R processes, using promises will maximize your performance far greater than our balancing between multiple R processes.

## What is asynchronous programming?

Synchronus code executes linearly. The following reads a CSV from the included URL.

```r
value <- read.csv("http://example.com/data/data.csv")
a <- 1+2
```

Before `a` can be assigned the value of `3`, R will execute an HTTP request to `http://example.com/data/data.csv`, download the CSV, and store it in the variable `value`. The R process is blocked until this is completed. There is no reason to wait for the CSV to complete downloading before continuing with the rest of your application's code, in particular because network functions can be offloaded to the operating system's event handler (libuv).

```r
promise <- future(read.csv("http://example.com/data/data.csv"))
a <- 1+2
```

The above will download the CSV in a non-blocking manner, meaning that `a` will be assigned 3 even if `read.csv` hasn't completed yet.

Asynchronous programming will execute an instruction, designated as asynchronous by the `promise` keyword, in a different thread, without waiting for it's result. You can offload long-running operations to a subsidiary R thread spawned by the promise library.

## Asynchronous R documentation

If you're processing CSVs, executing long-running code in your R Shiny app, you **should** use promises to speed up your application.

The following tutorials detail how to develop asynchronous R application.

* [Working with promises in R](https://rstudio.github.io/promises/articles/overview.html)
* [Async programming in R and Shiny](https://medium.com/@joe.cheng/async-programming-in-r-and-shiny-ebe8c5010790)
* [Case study: converting a Shiny app to async](https://rstudio.github.io/promises/articles/casestudy.html)
* [How to use the new R promises package](https://appsilon.com/an-example-of-how-to-use-the-new-r-promises-package/?nabe=4634331497365504:0\&utm_referrer=https%3A%2F%2Fwww.google.com%2F)