Periodic Timer Signals
This tutorial uses a static Jido.Plugin.Timer interval to send an Agent a
periodic Signal. A heartbeat is one application meaning for this Timer mode. It
is not a separate timer engine.
Timer only produces Signals. It does not detect missed beats or report liveness. Use a cron definition when work must align with a wall-clock slot.
Install Jido
Mix.install([
{:jido, github: "agentjido/jido", branch: "main"}
])
Start a Jido instance
Timer runs under the Agent activation, so the Agent must start through an instance.
{:ok, _instance} = Jido.start_link(name: HeartbeatGuide.Jido)
defmodule HeartbeatGuide.Wait do
def until(check, attempts \\ 200) do
cond do
check.() ->
:ok
attempts == 0 ->
raise "condition was not met in time"
true ->
Process.sleep(10)
until(check, attempts - 1)
end
end
end
Receive the default tick
Declare Timer with an interval and add a route for its Signal. Without
:signal_type, each tick is a Jido.Plugin.Timer.Signal.Tick with the type
"jido.agent.heartbeat" and the source "/plugin/heartbeat". The value of
:signal_data becomes the Action input.
defmodule HeartbeatGuide.Monitor do
use Jido.Agent,
name: "heartbeat_guide_monitor",
plugins: [{Jido.Plugin.Timer, %{interval: 20, signal_data: %{check: "disk"}}}]
state do
schema Jido.Joi.object(%{
beats: Jido.Joi.integer() |> Jido.Joi.default(0),
last: Jido.Joi.map() |> Jido.Joi.default(%{})
})
end
routes do
route "jido.agent.heartbeat" do
action input, context: context do
state = context.agent_state
{:ok,
%{
state
| beats: state.beats + 1,
last: %{type: context.signal.type, source: context.signal.source, input: input}
}}
end
end
end
end
{:ok, monitor} = Jido.start_agent(HeartbeatGuide.Jido, HeartbeatGuide.Monitor, id: "monitor-1")
:ok = Jido.AgentServer.await_ready(monitor)
The first tick arrives after one full interval. Wait for a few ticks and read the state:
:ok = HeartbeatGuide.Wait.until(fn -> Jido.AgentServer.snapshot(monitor).agent.state.beats >= 3 end)
Jido.AgentServer.snapshot(monitor).agent.state.last
# => %{type: "jido.agent.heartbeat", source: "/plugin/heartbeat", input: %{check: "disk"}}
Jido.AgentServer.plugin_state(monitor, Jido.Plugin.Timer)
# => {:ok, %{cron: %{}, every: %{heartbeat: %{status: :running, ...}}}}
The Timer stops with the Agent:
:ok = Jido.stop_agent(HeartbeatGuide.Jido, monitor)
Send your own Signal type
Set :signal_type and :source when the periodic Signal is a domain event.
The route then matches that type.
defmodule HeartbeatGuide.InvoiceSweeper do
use Jido.Agent,
name: "heartbeat_guide_invoice_sweeper",
plugins: [
{Jido.Plugin.Timer,
%{
interval: 20,
signal_type: "invoice.sweep_due",
signal_data: %{batch_size: 50},
source: "/billing/sweeper"
}}
]
state do
schema Jido.Joi.object(%{sweeps: Jido.Joi.list(Jido.Joi.integer()) |> Jido.Joi.default([])})
end
routes do
route "invoice.sweep_due" do
action %{batch_size: batch_size},
schema: Jido.Joi.object(%{batch_size: Jido.Joi.integer()}),
context: context do
{:ok, %{context.agent_state | sweeps: context.agent_state.sweeps ++ [batch_size]}}
end
end
end
end
{:ok, sweeper} =
Jido.start_agent(HeartbeatGuide.Jido, HeartbeatGuide.InvoiceSweeper, id: "sweeper-1")
:ok = Jido.AgentServer.await_ready(sweeper)
:ok = HeartbeatGuide.Wait.until(fn -> length(Jido.AgentServer.snapshot(sweeper).agent.state.sweeps) >= 2 end)
Jido.AgentServer.snapshot(sweeper).agent.state.sweeps |> Enum.take(2)
# => [50, 50]
:ok = Jido.stop_agent(HeartbeatGuide.Jido, sweeper)
Static Timer options are part of the Agent definition. Runtime options cannot replace them when the Agent starts.
Options
| Option | Default | Accepted values |
|---|---|---|
:interval |
5_000 |
Positive integer, in milliseconds. |
:signal_type |
"jido.agent.heartbeat" |
Non-empty, valid UTF-8 string. |
:signal_data |
%{} |
Plain map, not a struct. |
:source |
"/plugin/heartbeat" |
Non-empty URI reference. |
An invalid value fails the Agent definition with the message "Timer static interval options are invalid". An unknown option key is also rejected.
Delivery behavior
- The Timer casts each tick to the Agent. A long Turn can leave ticks queued behind it. Excess casts are dropped and logged at the postponed Turn limit.
- The next tick starts after the previous tick is sent. This is a fixed-delay interval, not wall-clock alignment.
- Each tick is a fresh Signal with a new ID.
- The interval definition is in the Agent
:timerstate. A runtime replacement starts one new full interval. Ticks missed while offline are not replayed.
Jido.Plugin.Heartbeat was removed. Use Jido.Plugin.Timer for all new and
migrated Agents.