A Flexible and Robust Sys.sleep() Replacement

Provides a near drop-in replacement for base::Sys.sleep() that allows more types of input to produce delays in the execution of code and can silence/prevent typical sources of error.


License Travis-CI Build Status CRAN_Status_Badge codecov.io

Why should I use it?

naptime makes delaying code execution in R more flexible and robust. It makes delaying code execution more flexible by supporting more data types than base::Sys.sleep(). It makes delaying code more robust by allowing errors in the delay specification to throw warnings instead of errors. Most notably, because naptime supports more input data types, you can use package:lubridate functions in conjunction with naptime to yield human readable time delays and intervals.

Consider the case of waiting one hour:

Sys.sleep(3600)

naptime(lubridate::hours(1))

Consider the case of wanting to start processing every hour for a job of an indeterminate duration:

repeat{
  start_time <- lubridate::now()
  # Do processing
  sleep_duration <- 3600 - as.numeric(lubridate::now() - start_time)
  if (sleep_duration > 0) {
    Sys.sleep(sleep_duration)
  }
}

# versus

repeat{
  start_time <- lubridate::now()
  # Do processing
  naptime(start_time + lubridate::hours(1))
}

How do I use it?

Because naptime() has nearly identical arguments and behavior as base::Sys.sleep() in response to numeric inputs, it can be nearly used as a drop-in replacement for base::Sys.sleep().

There are two notable differences in the behavior of Sys.sleep() and naptime():

  • For the input value of Inf base::Sys.sleep() will sleep indefinitely. In contrast, naptime::naptime() will produce an error (or if naptime.permissive = TRUE is set pause the default duration).
  • For a negative input value base::Sys.sleep() will produce an error. In contrast, naptime::naptime() will assume that the period of delay has already elapsed and move forward without further delay.

Options

All options are set via base::options().

  • naptime.default_delay. If left unchanged, the default delay is .1 seconds.
  • naptime.warnings. If left unchanged, the default is TRUE, to show warnings.
  • naptime.permissive. If left unchanged, the default is FALSE, to trigger errors on inputs that couldn't be converted into something sensible. If set TRUE, inputs that couldn't be converted into something sensible will result in a default delay.

Polymorphic inputs

naptime() accepts a wide variety of inputs.

Polymorphism for:

  • numeric: time in seconds to nap
naptime(1)
#> NULL
  • POSIXct: time at which the nap should stop (timezone is respected)
naptime(lubridate::now(tzone = "UTC")+lubridate::seconds(1))
#> NULL
  • Period: time from now at which the nap should stop
naptime(lubridate::seconds(1))
#> NULL
  • character: Date or date time at which nap should stop formatted as yyyy-mm-dd hh:mm:ss, time zone is assumed to be Sys.timezone() and hh:mm:ss is optional as three formats may be missing, cf. lubridate::ymd_hms()..
naptime(as.character(lubridate::now() + lubridate::seconds(1)))
#> NULL
  • difftime: difference in time to nap
naptime(difftime(lubridate::now() + lubridate::seconds(1), lubridate::now()))
#> NULL
  • logical: nap for default duration if TRUE, skip nap if FALSE
naptime(TRUE)
#> NULL
  • NULL; meaning no delay
naptime(NULL)
#> NULL
  • generic: By default this produces an error, however, you can set naptime.permissive as an option (or argument) that will cause this to nap for default duration instead.
naptime(glm(rnorm(5) ~ runif(5)), permissive = TRUE)
#> Warning: The time paramater was not scalar (length equal to 1)
#> Warning: unhandled input for naptime(): Error in (function (classes, fdef, mtable) : unable to find an inherited method for function 'naptime' for signature '"list"'
#> NULL
options(naptime.permissive = TRUE)
naptime(glm(rnorm(5) ~ runif(5)))
#> Warning: The time paramater was not scalar (length equal to 1)
 
#> Warning: unhandled input for naptime(): Error in (function (classes, fdef, mtable) : unable to find an inherited method for function 'naptime' for signature '"list"'
#> NULL

If you find a reasonable input-type for which naptime::naptime() doesn't have a reasonable response, please file an issue or PR in which you resolve the shortcoming.

How do I get it?

The current version is on CRAN, but you can fetch an early release of the upcoming build directly from github:

library(devtools)
install_github("drknexus/naptime")
library(naptime)

Author's Note

The initial draft of this code was written by Timothy Gann under a spec drafted by Russell Pierce. Many improvements and bug fixes to the original code, all packaging, and all tests were written by Russell Pierce. Russell Pierce is the current maintainer and responsible party for this package.

News

naptime 1.3.0

Breaking Change

  • Date parsing is again performed by lubridate. The limitation with this change is that character date input is again limited to only the yyyy-mm-dd hh:mm:ss format.

Other Notes

  • Removed naptime's dependency on anytime. Anytime was failing checks in some locales because of a bug in the underlying Boost library. Those failed checks reflected an issue that would cause naptime to underestimate the required nap duration by 1 hour on entry of character dates.

naptime 1.2.3

  • Kurt Hornik of CRAN reported problems with naptime 1.2.2 in some locales. This appears to be related to an issue in anytime that I am debugging in this non-CRAN development release.
  • I have also refactored the handling of Period class objects. It appears an eval(parse()) antipattern had leaked into the code. This is now resolved.

naptime 1.2.2

Character arguments for naptime are now parsed by package:anytime rather than lubridate::ymd_hms. This allows for greater flexibility in character nap specification. The previously supported truncated YYYY-MM-DD HH:MM:SS formats should parse the same as they did previously. So, this change is considered minor.

naptime 1.2.0

Formatting changes for CRAN deploy. Refer to naptime 1.1.0 NEWS for changes since the last CRAN version.

Behavior changes

  • lubridate parse warnings squelched

naptime 1.1.0

Behavior changes

  • Per request naptime is now quite a bit more discerning by default. If the argument provided isn't interpretable, naptime will throw as an error. The old permissive behavior that produces warnings and default delays can be more or less restored by setting the option naptime.permissive to TRUE or setting the permissive parameter as TRUE on any given naptime call (parameter overrides the option)
  • Logicals no longer produce a warning. Logical FALSE is interpreted as meaning 'no delay' and TRUE is interpreted as meaning default delay.
  • Calling naptime with a NULL no longer produces a delay or warning as this is interpreted as meaning 'no delay'.

New Features

  • naptime can take incompletely specified date times for delays in the future by leveraging lubridate::ymd_hms()'s truncated parameter. We now allow for three truncated formats.

Major Bug Fixes

  • naptime actually pauses for the default duration under error conditions rather than returning it as a variable
  • naptime no longer sometimes returns non-NULL values
  • naptime should now delay appropriately for long duration difftimes

naptime 1.0.0

  • Initial CRAN Submission
  • 100% Code Coverage
  • Polymorphism for:
  • numeric
  • NULL
  • POSIXct
  • Period
  • character
  • difftime
  • logical

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("naptime")

1.3.0 by Russell S. Pierce, a year ago


URL: https://github.com/drknexus/naptime


Report a bug at https://github.com/drknexus/naptime/issues


Browse source code at https://github.com/cran/naptime


Authors: Russell S. Pierce [aut, cre], Timothy Gann [aut]


Documentation:   PDF Manual  


GPL-2 license


Imports methods, lubridate

Suggests testthat, covr, knitr, rmarkdown


See at CRAN