Skip to contents

Introduction to onetime

Source: vignettes/onetime.Rmd
onetime.Rmd

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:

  • Tell users about new features in your package, without annoying them every time they load it.
  • Show a message, with the option to hide it in future.
  • Perform cleanup actions only once after an upgrade.

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

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=6001 on localhost:11225 at 08:17:12.706"
#> [2] "starting worker pid=6000 on localhost:11225 at 08:17:12.791"
#> [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 your package is used directly from the command line, the simplest option is to call functions using without_permission = "ask". This will ask the user for permission to store files if it has not been granted. If not, the action won’t be run.

    id <- "vignette-10"
onetime_message("Thank you for your kind applause.", 
                id = id,
                without_permission = "ask")
    #> The onetime package requests to store files in '~/Library/Application Support/onetime'.
#> Is this OK? [Yn]
#> Thank you for your kind applause.

  • If you want more control over when and how you ask users, you can call check_ok_to_store(ask = TRUE) manually before using onetime functions.

    check_ok_to_store(
  ask = TRUE, 
  message = "Please let this package store files in your config directory '%s'.",
  confirm_prompt = "OK? (Y/N)"
  )
    #> Please let this package store files in your config directory'~/Library/Application Support/onetime'
#> OK? (Y/N)

  • In code which might be run non-interactively, or as part of a long-running command, you can manually call set_ok_to_store(TRUE) before you use other onetime functions. This will grant permission to store files, and will print a warning to the user explaining how they can change this:

    set_ok_to_store(TRUE)
#> Granting the onetime package permission to store lockfiles on this computer.
#> Lockfiles are stored beneath '/tmp/RtmpKbIihe'.
#> You can revoke permission by calling:
#>   onetime::set_ok_to_store(FALSE)

  • By default, configuration files are stored beneath rappdirs::user_config_dir(). If you want to store configuration files in a non-standard directory, set options(onetime.dir = <path to directory>). When this option is set, onetime assumes that permission has been granted. So, you can also use this approach to avoid raising the issue of permissions with the user - so long as you don’t plan to submit your package to CRAN.

    Use this mechanism with care. Package authors should always set options(onetime.dir) locally within their functions and set it back to its original value afterwards. Otherwise you risk changing the directory for other packages, or overwriting the user’s preferred value. You can do this using withr::local_options():

    my_func <- function () {
  withr::local_options(onetime.dir = "path to preferred directory")
  onetime_message("Hit it hard with your spoon.",
                  "They always break in the end.",
                  id = "flick-1")
}

    or in base R:

    my_func <- function () {
  oo <- options(onetime.dir = "path to preferred directory")
  on.exit(options(oo))
  ...
}

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: