Introduction to onetime

Motivation

Sometimes package authors want to run code only once for a given user on a given computer. Not just “once per session”, but “only once ever” or “only once per month” at most. Here are some use cases:

The onetime package lets you do this.

Onetime is a lightweight package, with just two package dependencies, rappdirs and filelock. Its total size including dependencies is less than 50 Kb. So it is cheap to include as a dependency in your own package.

Setup

You can install onetime from CRAN like this:

install.packages("onetime")

Next, on the R command line, run

library(onetime)
check_ok_to_store(ask = TRUE)

If you haven’t used onetime before, you will be asked if it is OK to store files in onetime’s configuration directory. Answer Y. Now you can try out onetime’s functions.

Basic usage

Let’s use onetime_message() to show a message just once. On the command line, enter:

id <- "vignette-1"
onetime_message("I shall say this only once!", id = id)
#> I shall say this only once!

You should see the message, displayed using the base R message() function.

Now if you enter the same code again:

onetime_message("I shall say this only once!", id = id)

… you won’t see anything! Even if you restart R and again run onetime_message() with the same id, nothing will be shown. Onetime has stored a file on your computer to record that the message was already shown, and it doesn’t show it again.

You still won’t see any message, even if you change the message itself:

onetime_message("Does nobody hear the cries of an poor old woman?", id = id)

That’s because onetime identifies actions by their id. If you change the id, you can send a new message:

id <- "vignette-2"
onetime_message("I repeat... I shall say this only once!", id = id)
#> I repeat... I shall say this only once!

You aren’t limited to sending messages. You can also give warnings:

id <- "vignette-3"
onetime_warning("you cannot expect me to shoot everyone in the town. ",
                "I'm unpopular enough as it is!", id = id)
#> Warning: you cannot expect me to shoot everyone in the town. I'm unpopular
#> enough as it is!

You can print package startup messages using onetime_startup_message(). If the rlang package is installed, you can also use onetime_rlang_inform() and onetime_rlang_warn() to print messages and warnings using rlang format:

id <- "vignette-4"
onetime_rlang_inform(c(
                       "Let that be a lesson to you.", 
                       i = "Never again will you burn my toast."
                       ), 
                     id = id)
#> Let that be a lesson to you.
#> ℹ Never again will you burn my toast.

Underlying all these functions is onetime_do(), which allows you to run arbitrary code just once:

id <- "vignette-5"
onetime_do(light_the_candle_with_the_handle(), id = id)
#> If we kill him with the pill from the till
#> by making with it the drug in the jug, you need not
#> light the candle with the handle on the Gateau from the Chateau!

Onetime uses file locks to avoid race conditions. So even if you use multiple R processes, a onetime action will be run only once:


# NB: This chunk will only be run on Unix-alikes

cl <- parallel::makeCluster(2, outfile = "check.txt")
otd <- getOption("onetime.dir")

results <- parallel::parSapply(cl, 1:20, otd = otd,
  function (x, otd) {
    options(onetime.dir = otd)
    onetime::onetime_message("I will say this only once!", id = "vignette-6")
  }
)
parallel::stopCluster(cl)

table(results)
#> results
#> FALSE  TRUE 
#>    19     1

readLines("check.txt")
#> [1] "starting worker pid=51014 on localhost:11632 at 04:31:00.049"
#> [2] "starting worker pid=51013 on localhost:11632 at 04:31:00.049"
#> [3] "I will say this only once!"

Allowing the user to hide a message

Sometimes you may wish to show a message to the user but give them the option to hide it in future. You can do this with onetime_message_confirm().

In interactive sessions, this will ask the user if they want to show the message again:

id <- "vignette-7"
onetime_message_confirm(
  "What are you doing with that serving girl in your arms?",
  id = id)
#> What are you doing with that serving girl in your arms?
#> Show this message again? [yN]

In non-interactive sessions, it will tell the user how they can hide the message in future:

id <- "vignette-8"
onetime_message_confirm("One drink and... all is quiet on the Western Front.", 
            id = id)
#> One drink and... all is quiet on the Western Front.
#> To hide this message in future, run:
#>   onetime::onetime_mark_as_done(id = "vignette-8")

Setting an expiry time

You can set an expiry time by passing a difftime() object to the expiry argument of these functions. For example, this will print a message, but only if it has not been printed in the past week:

id <- "vignette-9"
onetime_message("Good moaning!", 
                id = id, 
                expiry = as.difftime(1, "weeks")
                )
#> Good moaning!

Using onetime in your package

Onetime works by writing a file, typically to a folder in the user’s configuration directory. As a package author, it is your responsibility to check for permission to store lockfiles. CRAN policy demands that you do this. Onetime functions will check for this permission, and by default won’t store the file until it has been granted.

You have several options to handle this:

If onetime has already been installed by a different package, then it is likely that the user will have already granted file permissions, and onetime functions will just work.

Utility functions

onetime_been_done() checks whether an action has been performed:

onetime_been_done("vignette-1")
#> [1] TRUE
onetime_been_done("vignette-unused")
#> [1] FALSE

To reset a particular id, so that functions will be run again, use onetime_reset():

onetime_reset(id = "vignette-1")
onetime_message("I shall say this only once!", id = "vignette-1")
#> I shall say this only once!

From version 0.2.0 of the package, you can use onetime_mark_as_done() to manually mark a particular action as done:

id <- "vignette-11"
onetime_mark_as_done(id)
# Won't be shown:
onetime_message("In my opinion, a whole Meccano set has fallen apart in there.",
            id = id)

Going further

More information is available on the onetime website: