Mob.Event.Throttle (mob v0.6.6)

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}