@spec add_jitter(non_neg_integer(), float()) :: non_neg_integer()

Adds jitter to a timer interval to prevent thundering herd.

Examples

# Add +/- 10% jitter to 5 second interval
interval = TimerManager.add_jitter(5000, 0.1)

@spec add_timer(map(), atom(), timer_type(), non_neg_integer()) :: map()

Manages multiple timers in a map, useful for GenServer state.

Examples

# Start a new timer in the timers map
timers = TimerManager.add_timer(state.timers, :heartbeat, :interval, 5000)

# Cancel and remove a timer
timers = TimerManager.remove_timer(state.timers, :heartbeat)

@spec cancel_all_timers(map()) :: :ok

Cancels all timers in a map, useful for GenServer terminate.

Examples

TimerManager.cancel_all_timers(state.timers)

@spec cancel_timer(timer_ref()) :: {:ok, boolean() | :ok}

Cancels a timer and returns whether it was successfully cancelled.

Examples

{:ok, cancelled} = TimerManager.cancel_timer(timer_ref)

@spec exponential_backoff(
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer()
) :: non_neg_integer()

Calculates next timer interval for exponential backoff.

Examples

# First retry after 1 second, then 2, 4, 8, up to max 30 seconds
delay = TimerManager.exponential_backoff(attempt, 1000, 30_000)

Common timer intervals as constants for consistency.

@spec safe_cancel(timer_ref()) :: :ok

Safely cancels a timer if it exists, ignoring errors.

Examples

TimerManager.safe_cancel(timer_ref)

@spec send_after(timer_msg(), non_neg_integer()) :: timer_ref()

Starts a one-time delayed timer that sends a message after a delay.

Examples

# Send :timeout message after 30 seconds
ref = TimerManager.send_after(:timeout, 30_000)

# Send {:retry, attempt_num} after 1 second
ref = TimerManager.send_after({:retry, 1}, 1000)

@spec start_interval(timer_msg(), non_neg_integer()) ::
  {:ok, timer_ref()} | {:error, term()}

Starts a periodic timer that sends a message at regular intervals.

Examples

# Send :cleanup message every hour
{:ok, ref} = TimerManager.start_interval(:cleanup, 3_600_000)

# Send {:check_status, :database} every 5 seconds
{:ok, ref} = TimerManager.start_interval({:check_status, :database}, 5000)