reactive.throttle
reactive.throttle(
delay_secs=MISSING,
fn_delay_secs=MISSING,
*,
priority=100,
session=MISSING,
)Invalidate the readers of a reactive function at most once per time window.
When the decorated function's reactive dependencies change, its readers are invalidated right away unless they were already invalidated in the last delay_secs. In that case they are invalidated once at the end of the window. Unlike debounce, new changes don't restart the window, so a source that keeps changing still updates its readers regularly.
With a 3-unit window, where each character is one unit of time and o is an invalidation:
source: ooo-oo-oo----
throttle: o--o--o--o---
Parameters
fn :-
Only when called as
throttle(fn, delay_secs)instead of as a decorator: the no-argument function to limit, such as acalcor an input (input.text). delay_secs : Any = MISSING-
The minimum number of seconds between invalidations. You may also pass a synchronous no-argument function or
calcthat returns the number of seconds, for example to let the user control the window. It must always return a number. If it stops early (for example withreq), the timer doesn’t start, and readers aren’t invalidated until it returns a number again. If it raises any other error, the session closes. priority : int = 100-
Throttling is implemented with
effects. Use this argument to set their priority. It should be higher than the priority of the effects and outputs that read the throttled function (which default to 0). session : MISSING_TYPE | Session | None = MISSING-
A
Sessioninstance. If not provided, a session is inferred viaget_current_session.
Returns
Note
The decorated function may still run as often as before (or more often). Only the invalidation of its readers is slowed down, so use this when the decorated function is cheap and the work downstream of it is expensive.
Times are minimums: if the event loop is busy when the timer is due, the invalidation waits until it is free.
Tip
Like event, this decorator must be applied before @reactive.calc (i.e., @reactive.calc must be above it). It can’t be used with @reactive.effect or @render.xx, which have no value for readers to wait on: read the limited calc from them instead. An effect can react to it with @reactive.event(<calc>).
To limit a function you already have, such as an existing calc or an input, call it as throttle(fn, delay_secs). That returns a calc, so there’s no decorator to put in order.
See Also
Examples
#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400
## file: app.py
from shiny import reactive
from shiny.express import input, render, ui
ui.input_text("text", "Type quickly")
# Update at most once per second
@reactive.calc
@reactive.throttle(1)
def text_throttled():
return input.text()
@render.text
def raw():
return f"Raw: {input.text()}"
@render.text
def throttled():
return f"Throttled: {text_throttled()}"