Search documentation of mob

# Mob.Event.Throttle (mob v0.6.18)

Copy Markdown View Source

Throttle / debounce config for high-frequency event subscriptions.

See `guides/event_model.md` and `PLAN.md` Batch 5.

## Forms accepted

    on_scroll: {pid, tag}                        # default: 30 Hz throttle
    on_scroll: {pid, tag, throttle: 100}         # 10 Hz
    on_scroll: {pid, tag, throttle: 0}           # raw firing rate (no throttle)
    on_scroll: {pid, tag, debounce: 200}         # only after 200 ms of stillness
    on_scroll: {pid, tag, throttle: 50, delta: 4} # 20 Hz + 4 px delta threshold

Defaults differ by event type:

Event | Default throttle | Default delta
--- | --- | ---
`:scroll` | 30 Hz (33 ms) | 1 px
`:drag` | 60 Hz (16 ms) | 1 px
`:pinch` | 60 Hz (16 ms) | 0.01 (1%)
`:rotate` | 60 Hz (16 ms) | 1°
`:pointer_move` | 30 Hz (33 ms) | 4 px

## Resulting native config

Parsed config is passed across the NIF boundary as a small map (or atom for the default). The native side stores this per registered handle and enforces it before any `enif_send` is issued.

## Summary

### Types

config()
event_kind()

### Functions

default?(kind, config)

Returns true if the throttle config equals the defaults — used by the renderer to skip serialising trivial configs across the NIF boundary.

default_for(kind)

Returns the default throttle config for an event kind.

parse(kind, opts)

Parse a user-supplied opts list into a normalised config.

## Types

# config()

    @type config() :: %{
      throttle_ms: non_neg_integer(),
      debounce_ms: non_neg_integer(),
      delta_threshold: number(),
      leading: boolean(),
      trailing: boolean()
    }

# event_kind()

    @type event_kind() :: :scroll | :drag | :pinch | :rotate | :pointer_move

## Functions

# default?(kind, config)

    @spec default?(event_kind(), config()) :: boolean()

Returns true if the throttle config equals the defaults — used by the renderer to skip serialising trivial configs across the NIF boundary.

# default_for(kind)

    @spec default_for(event_kind()) :: config()

Returns the default throttle config for an event kind.

    iex> Mob.Event.Throttle.default_for(:scroll)
    %{throttle_ms: 33, debounce_ms: 0, delta_threshold: 1, leading: true, trailing: true}

    iex> Mob.Event.Throttle.default_for(:pointer_move).throttle_ms
    33

# parse(kind, opts)

    @spec parse(
      event_kind(),
      keyword()
    ) :: config()

Parse a user-supplied opts list into a normalised config.

Always returns a complete config (defaults filled in). Validates that numeric fields are non-negative and the right types.

    iex> Mob.Event.Throttle.parse(:scroll, [])
    %{throttle_ms: 33, debounce_ms: 0, delta_threshold: 1, leading: true, trailing: true}

    iex> Mob.Event.Throttle.parse(:scroll, throttle: 100)
    %{throttle_ms: 100, debounce_ms: 0, delta_threshold: 1, leading: true, trailing: true}

    iex> Mob.Event.Throttle.parse(:scroll, throttle: 0)
    %{throttle_ms: 0, debounce_ms: 0, delta_threshold: 1, leading: true, trailing: true}

    iex> Mob.Event.Throttle.parse(:scroll, debounce: 200)
    %{throttle_ms: 33, debounce_ms: 200, delta_threshold: 1, leading: true, trailing: true}