Jido.Scheduler (Jido v2.3.0)

Per-agent cron scheduling with internal timer processes.

Jido.Scheduler is intentionally lightweight and process-local: each registered cron job is backed by a dedicated process owned by the caller (typically the owning Jido.AgentServer).

The runtime stores live job processes in AgentServer.State.cron_jobs and separately stores durable schedule definitions in AgentServer.State.cron_specs. The durable specs are persisted through Jido.Persist for InstanceManager- managed agents.

Summary

Types

cron_spec()

cron_specs()

invalid_cron_spec()

Functions

alive?(pid)

Checks if a cron job process is still alive.

build_cron_spec(cron_expression, message, timezone \\ nil)

Build a normalized durable cron spec map.

cancel(pid)

Cancels a running cron job.

cron_specs_state_key()

Reserved internal agent-state key used to stage durable cron specs across hibernate/thaw boundaries.

normalize_cron_specs(specs)

Normalize a persisted cron-spec map, dropping malformed entries.

run_every(fun, cron_expr, opts \\ [])

Starts a recurring cron job with a function.

run_every(module, function, args, cron_expr, opts \\ [])

Starts a recurring cron job.

Types

cron_spec()

@type cron_spec() :: %{
  cron_expression: String.t(),
  message: term(),
  timezone: String.t()
}

cron_specs()

@type cron_specs() :: %{optional(term()) => cron_spec()}

invalid_cron_spec()

@type invalid_cron_spec() :: {term(), term(), term()}

Functions

alive?(pid)

@spec alive?(pid()) :: boolean()

Checks if a cron job process is still alive.

build_cron_spec(cron_expression, message, timezone \\ nil)

@spec build_cron_spec(String.t(), term(), String.t() | nil) :: cron_spec()

Build a normalized durable cron spec map.

cancel(pid)

@spec cancel(pid()) :: :ok

Cancels a running cron job.

Examples

{:ok, pid} = Jido.Scheduler.run_every(MyModule, :work, [], "* * * * *")
:ok = Jido.Scheduler.cancel(pid)

cron_specs_state_key()

@spec cron_specs_state_key() :: atom()

Reserved internal agent-state key used to stage durable cron specs across hibernate/thaw boundaries.

normalize_cron_specs(specs)

@spec normalize_cron_specs(term()) :: %{optional(term()) => cron_spec()}

Normalize a persisted cron-spec map, dropping malformed entries.

run_every(fun, cron_expr, opts \\ [])

@spec run_every((-> any()), term(), term()) :: {:ok, pid()} | {:error, term()}

Starts a recurring cron job with a function.

Examples

{:ok, pid} = Jido.Scheduler.run_every(fn -> IO.puts("tick") end, "* * * * *")

run_every(module, function, args, cron_expr, opts \\ [])

@spec run_every(module(), atom(), list(), String.t(), keyword()) ::
  {:ok, pid()} | {:error, term()}

Starts a recurring cron job.

Returns {:ok, pid} where pid is the scheduler job process that can be used to cancel the job later.

Options

:timezone - Timezone for the cron expression (default: "Etc/UTC")

Examples

{:ok, pid} = Jido.Scheduler.run_every(MyModule, :work, [], "*/5 * * * *")
{:ok, pid} = Jido.Scheduler.run_every(fn -> IO.puts("tick") end, "* * * * *")