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 a calc or 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 calc that 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 with req), 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 Session instance. If not provided, a session is inferred via get_current_session.

Returns

: Any

A decorator for a no-argument function (regular or async). The result returns the decorated function’s value, but its readers are invalidated at most once per delay_secs. Called as (fn, delay_secs), it returns a calc that does the same for fn.

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 App, Inputs, Outputs, Session, reactive, render, ui

app_ui = ui.page_fluid(
    ui.input_text("text", "Type quickly"),
    ui.output_text("raw"),
    ui.output_text("throttled"),
)


def server(input: Inputs, output: Outputs, session: Session):
    # 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()}"


app = App(app_ui, server)