The basics
Use ratelimitr to limit the rate at which functions are called. A
rate-limited function that allows n calls per
period will never have a window of time of length
period that includes more than n calls.
library(ratelimitr)
f <- function() NULL
# create a version of f that can only be called 10 times per second
f_lim <- limit_rate(f, rate(n = 10, period = 1))
# time without limiting
system.time(replicate(11, f()))
## user system elapsed
## 0.001 0.000 0.001
# time with limiting
system.time(replicate(11, f_lim()))
## user system elapsed
## 0.004 0.000 1.046
Multiple rates
Published rate limits often have multiple types of limits. Here is an
example of limiting a function so that it never evaluates more than 10
times per .1 seconds, but additionally never evaluates more than 50
times per 1 second.
f_lim <- limit_rate(
f,
rate(n = 10, period = .1),
rate(n = 50, period = 1)
)
# 10 calls do not trigger the rate limit
system.time( replicate(10, f_lim()) )
## user system elapsed
## 0.001 0.000 0.000
# note that reset does not modify its argument, but returns a new
# rate-limited function with a fresh timer
f_lim <- reset(f_lim)
system.time( replicate(11, f_lim()) )
## user system elapsed
## 0.001 0.000 0.164
# similarly, 50 calls don't trigger the second rate limit
f_lim <- reset(f_lim)
system.time( replicate(50, f_lim()) )
## user system elapsed
## 0.009 0.000 0.574
# but 51 calls do:
f_lim <- reset(f_lim)
system.time( replicate(51, f_lim()) )
## user system elapsed
## 0.014 0.001 1.042
Multiple functions sharing one (or more) rate limit(s)
To limit a group of functions together, just pass
limit_rate a list of functions instead of a single
function. Make sure the list is named, the names will be how you access
the rate-limited versions of the functions:
f <- function() "f"
g <- function() "g"
h <- function() "h"
# passing a named list to limit_rate
limited <- limit_rate(
list(f = f, g = g, h = h),
rate(n = 3, period = 1)
)
# now limited is a list of functions that share a rate limit. examples:
limited$f()
## [1] "f"
## [1] "g"
The new functions are subject to a single rate limit, regardless of
which ones are called or in what order they are called.
# the first three function calls should not trigger a delay
system.time(
{limited$f(); limited$g(); limited$h()}
)
## user system elapsed
## 0.001 0.000 0.001
limited <- reset(limited)
# but to evaluate a fourth function call, there will be a delay
system.time({
limited$f()
limited$g()
limited$h()
limited$f()
})
## user system elapsed
## 0.002 0.000 1.068
ratelimitr/README.md 0000644 0001762 0000144 00000010300 15073007175 013704 0 ustar ligges users ratelimitr
================
[](https://cran.r-project.org/package=ratelimitr)
[](https://github.com/tarakc02/ratelimitr/actions/workflows/R-CMD-check.yaml)
## Installation
This package is available on CRAN. To install:
``` r
install.packages("ratelimitr")
```
## Introduction
Use ratelimitr to limit the rate at which functions are called. A
rate-limited function that allows `n` calls per `period` will never have
a window of time of length `period` that includes more than `n` calls.
``` r
library(ratelimitr)
f <- function() NULL
# create a version of f that can only be called 10 times per second
f_lim <- limit_rate(f, rate(n = 10, period = 1))
# time without limiting
system.time(replicate(11, f()))
#> user system elapsed
#> 0 0 0
# time with limiting
system.time(replicate(11, f_lim()))
#> user system elapsed
#> 0.005 0.000 1.046
```
## Multiple rates
Published rate limits often have multiple types of limits. Here is an
example of limiting a function so that it never evaluates more than 10
times per .1 seconds, but additionally never evaluates more than 50
times per 1 second.
``` r
f_lim <- limit_rate(
f,
rate(n = 10, period = .1),
rate(n = 50, period = 1)
)
# 10 calls do not trigger the rate limit
system.time(replicate(10, f_lim()))
#> user system elapsed
#> 0.000 0.000 0.001
# sleeping in between tests to re-set the rate limit timer
Sys.sleep(1)
# 11 function calls do trigger the rate limit
system.time(replicate(11, f_lim())); Sys.sleep(1)
#> user system elapsed
#> 0.001 0.001 0.143
# similarly, 50 calls don't trigger the second rate limit
system.time(replicate(50, f_lim())); Sys.sleep(1)
#> user system elapsed
#> 0.009 0.000 0.574
# but 51 calls do:
system.time(replicate(51, f_lim())); Sys.sleep(1)
#> user system elapsed
#> 0.012 0.001 1.041
```
## Multiple functions sharing one (or more) rate limit(s)
To limit a group of functions together, just pass `limit_rate` a list of
functions instead of a single function. Make sure the list is named, the
names will be how you access the rate-limited versions of the functions:
``` r
f <- function() 1
g <- function() 2
h <- function() 3
# passing a named list to limit_rate
limited <- limit_rate(list(f = f, g = g, h = h), rate(n = 3, period = 1))
# now limited is a list of functions that share a rate limit. examples:
limited$f()
#> [1] 1
limited$g()
#> [1] 2
```
The new functions are subject to a single rate limit, regardless of
which ones are called or in what order they are called.
``` r
# the first three function calls should not trigger a delay
system.time(
{limited$f(); limited$g(); limited$h()}
)
#> user system elapsed
#> 0 0 0
# sleep in between tests to reset the rate limit timer
Sys.sleep(1)
# but to evaluate a fourth function call, there will be a delay
system.time(
{limited$f(); limited$g(); limited$h(); limited$f()}
)
#> user system elapsed
#> 0.000 0.001 1.043
```
## Limitations
`limit_rate` is not safe to use in parallel.
The precision with which you can measure the length of time that has
elapsed between two events is constrained to some degree, dependent on
your operating system. In order to guarantee compliance with rate
limits, this package truncates the time (specifically taking the ceiling
or the floor based on which would give the most conservative estimate of
elapsed time), rounding to the fraction specified in the `precision`
argument of `token_dispenser` – the default is 60, meaning time
measurements are taken up to the 1/60th of a second. While the
conservative measurements of elapsed time make it impossible to overrun
the rate limit by a tiny fraction of a second (see [Issue
3](https://github.com/tarakc02/ratelimitr/issues/3)), they also will
result in waiting times that are slightly longer than necessary (using
the default `precision` of 60, waiting times will be .01-.03 seconds
longer than necessary).
ratelimitr/build/ 0000755 0001762 0000144 00000000000 15073007355 013532 5 ustar ligges users ratelimitr/build/vignette.rds 0000644 0001762 0000144 00000000327 15073007355 016073 0 ustar ligges users mQ
0 nn(y)@൬ *]exɝnV I}zB
B< R?0_cJ[lRPM"\p ƚtѢv +{hK
,&!Έyή{س{'ȱ0f#?Ő3 )e
K={hU=4D쬀ot $q ratelimitr/man/ 0000755 0001762 0000144 00000000000 15072043072 013201 5 ustar ligges users ratelimitr/man/limit_rate.Rd 0000644 0001762 0000144 00000003033 15072043072 015620 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/limit-rate.R
\name{limit_rate}
\alias{limit_rate}
\alias{limit_rate.list}
\alias{limit_rate.function_list}
\alias{limit_rate.function}
\title{Limit the rate at which a function will execute}
\usage{
limit_rate(f, ..., precision = 60)
\method{limit_rate}{list}(f, ..., precision = 60)
\method{limit_rate}{function_list}(f, ..., precision = 60)
\method{limit_rate}{function}(f, ..., precision = 60)
}
\arguments{
\item{f}{A single function to be rate-limited, or a named list of functions}
\item{...}{One or more rates, created using \code{\link{rate}}}
\item{precision}{The precision with which time intervals can be measured, in hertz}
}
\value{
If \code{f} is a single function, then a new function with the same
signature and (eventual) behavior as the original function, but rate limited.
If \code{f} is a named list of functions, then a new list of functions with the
same names and signatures, but collectively bound by a shared rate limit.
}
\description{
Limit the rate at which a function will execute
}
\examples{
## limiting a single function
f <- limit_rate(Sys.time, rate(n = 5, period = .1))
res <- replicate(10, f())
## show the elapsed time between each function call:
round(res[-1] - head(res, -1), 3)
## for multiple functions, make sure the list is named:
f <- function() 1
g <- function() 2
limited <- limit_rate(list(f = f, g = g), rate(n = 1, period = .1))
system.time({limited$f(); limited$g()})
}
\seealso{
\code{\link{rate}}, \code{\link{UPDATE_RATE}}
}
ratelimitr/man/get_function.Rd 0000644 0001762 0000144 00000000557 15072043072 016163 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/accessors.R
\name{get_function}
\alias{get_function}
\title{Access the original function from a rate limited function}
\usage{
get_function(f)
}
\arguments{
\item{f}{A rate limited function or group of functions}
}
\description{
Access the original function from a rate limited function
}
ratelimitr/man/get_precision.Rd 0000644 0001762 0000144 00000000476 15072043072 016331 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/accessors.R
\name{get_precision}
\alias{get_precision}
\title{Access the rate limit precision}
\usage{
get_precision(f)
}
\arguments{
\item{f}{A rate limited function or group of functions}
}
\description{
Access the rate limit precision
}
ratelimitr/man/reset.Rd 0000644 0001762 0000144 00000001372 15072043072 014615 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reset.R
\name{reset}
\alias{reset}
\title{Re-create a rate-limited function}
\usage{
reset(f)
}
\arguments{
\item{f}{A rate-limited function or group of functions}
}
\description{
This function does not modify the original rate-limited function, instead
it returns a new function with the same rate limits (but no memory of prior
function calls).
}
\examples{
f <- function() NULL
f_lim <- limit_rate(f, rate(n = 1, period = .1))
f_lim() ## the next call to f_lim will trigger the rate limit
f_lim2 <- reset(f_lim) ## but f_lim2 has a fresh start
## f_lim2 behaves as though no calls have been made
system.time(f_lim2())
## while f_lim is still constrained
system.time(f_lim())
}
ratelimitr/man/rate.Rd 0000644 0001762 0000144 00000000755 15072043072 014432 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rate.R
\name{rate}
\alias{rate}
\title{Create a new rate}
\usage{
rate(n, period)
}
\arguments{
\item{n}{Number of allowed events within a period}
\item{period}{Length (in seconds) of measurement period}
}
\description{
Create a new rate
}
\examples{
## a function
f <- function() NULL
## limit f to 10 calls per second
limited_f <- limit_rate(f, rate(n = 10, period = 1))
}
\seealso{
\code{\link{limit_rate}}
}
ratelimitr/man/UPDATE_RATE.Rd 0000644 0001762 0000144 00000002020 15072043072 015257 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/update-rate.R
\name{UPDATE_RATE}
\alias{UPDATE_RATE}
\title{Update the rate limit of an existing rate limited function}
\usage{
UPDATE_RATE(lf, ..., precision = 60)
}
\arguments{
\item{lf}{A rate-limited function or group of functions}
\item{...}{One or more rates, created using \code{\link{rate}}}
\item{precision}{The precision with which time intervals can be measured, in hertz}
}
\description{
\code{UPDATE_RATE} modifies an existing rate-limited function in place,
changing the rate limits without otherwise altering the function's behavior.
When a rate limited function has its rate limits updated, the previous rate
limits and any calls that would have counted against those rate limits are
immediately forgotten, and only the new rate limits are obeyed going forward.
}
\examples{
f <- function() NULL
f_lim <- limit_rate(f, rate(n = 1, period = .1))
# update the rate limits to 2 calls per .1 second
UPDATE_RATE(f_lim, rate(n = 2, period = .1))
}
ratelimitr/man/get_rates.Rd 0000644 0001762 0000144 00000000532 15072043072 015445 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/accessors.R
\name{get_rates}
\alias{get_rates}
\title{Access the rate limit(s) of a rate limited function}
\usage{
get_rates(f)
}
\arguments{
\item{f}{A rate limited function or group of functions}
}
\description{
Access the rate limit(s) of a rate limited function
}
ratelimitr/DESCRIPTION 0000644 0001762 0000144 00000001416 15073200462 014135 0 ustar ligges users Package: ratelimitr
Type: Package
Title: Rate Limiting for R
Version: 0.4.2
Authors@R: person(given = "Tarak",
family = "Shah",
role = c("aut", "cre", "cph"),
email = "tarak.shah@gmail.com")
Description: Allows to limit the rate at which one or more functions can be called.
License: MIT + file LICENSE
RoxygenNote: 6.1.0
Suggests: testthat, microbenchmark, knitr, rmarkdown, covr
Imports: assertthat
VignetteBuilder: knitr
URL: https://github.com/tarakc02/ratelimitr
BugReports: https://github.com/tarakc02/ratelimitr/issues
NeedsCompilation: no
Packaged: 2025-10-12 20:26:22 UTC; tshah
Author: Tarak Shah [aut, cre, cph]
Maintainer: Tarak Shah