Jido.Sensors.Cron (Jido v1.1.0-rc.2)
View SourceA sensor that emits signals based on cron schedules via Quantum.
By default, the sensor uses the Quantum scheduler referenced by :jido_quantum
,
but you can override the scheduler name by specifying quantum_ref
in the sensor's
start options.
You can also specify a list of cron jobs to be automatically added at startup via
the jobs
parameter. Each entry can be:
{<Crontab.CronExpression>, <task>}
-> auto-generated job name{<job_name>, <Crontab.CronExpression>, <task>}
-> manual job name
Example Usage:
{:ok, sensor} =
Jido.Sensors.Cron.start_link(
id: "my_cron_sensor",
target: {:bus, [target: :my_bus, stream: "some_stream"]},
scheduler: Jido.Scheduler,
jobs: [
# Auto-named job
{~e"* * * * * *"e, :task1},
# Named job
{:my_job, ~e"0 */2 * * * *"e, :task2}
]
)
# Add a new job later
:ok = Jido.Sensors.Cron.add_job(sensor, :manual_job, ~e"* * * * *"e, :another_task)
# Remove the job
:ok = Jido.Sensors.Cron.remove_job(sensor, :manual_job)
# Run a job immediately
:ok = Jido.Sensors.Cron.run_job(sensor, :my_job)
Summary
Functions
Activates a cron job by name.
Adds a new cron job with the given name, schedule, and task.
Returns the configured category of the sensor.
Returns a specification to start this module under a supervisor.
Deactivates a cron job by name.
Returns the configured description of the sensor.
Retrieves the complete configuration of a sensor.
Retrieves a specific configuration value from a sensor.
Returns the configured name of the sensor.
Removes a cron job by name.
Runs a job immediately (outside its normal schedule).
Returns the configured schema for the sensor.
Updates multiple configuration values for a sensor.
Updates a single configuration value for a sensor.
Starts a new Sensor process.
Returns the configured tags for the sensor.
Converts the sensor metadata to a JSON-compatible map.
Returns the configured version of the sensor.
Types
@type sensor_result() :: Jido.Sensor.sensor_result()
@type t() :: Jido.Sensor.t()
Functions
@spec activate_job(GenServer.server(), atom()) :: :ok | {:error, any()}
Activates a cron job by name.
@spec add_job(GenServer.server(), atom(), Crontab.CronExpression.t(), any()) :: :ok | {:error, any()}
Adds a new cron job with the given name, schedule, and task.
name
must be an atom.
schedule
is a Crontab.CronExpression (supports ~e""
sigil or built manually).
task
can be any term you want included in the dispatched signal's data.
@spec category() :: atom() | nil
Returns the configured category of the sensor.
Returns a specification to start this module under a supervisor.
See Supervisor
.
@spec deactivate_job(GenServer.server(), atom()) :: :ok | {:error, any()}
Deactivates a cron job by name.
@spec description() :: String.t() | nil
Returns the configured description of the sensor.
@spec get_config(Jido.Sensor.t()) :: {:ok, map()} | {:error, any()}
Retrieves the complete configuration of a sensor.
Parameters
sensor
- The sensor to get configuration from. Can be a PID, atom name, or string name.
Return Values
{:ok, config}
- The complete configuration map{:error, reason}
- If the sensor cannot be found or accessed
Examples
iex> {:ok, config} = MySensor.get_config(sensor_pid)
{:ok, %{id: "sensor1", target: {:bus, :my_bus}}}
iex> MySensor.get_config(:nonexistent_sensor)
{:error, :invalid_sensor}
@spec get_config(Jido.Sensor.t(), atom()) :: {:ok, any()} | {:error, :not_found | any()}
Retrieves a specific configuration value from a sensor.
Parameters
sensor
- The sensor to get configuration from. Can be a PID, atom name, or string name.key
- The configuration key to retrieve
Return Values
{:ok, value}
- The configuration value for the key{:error, :not_found}
- If the key does not exist{:error, reason}
- If the sensor cannot be found or accessed
Examples
iex> {:ok, value} = MySensor.get_config(sensor_pid, :target)
{:ok, {:bus, :my_bus}}
iex> MySensor.get_config(sensor_pid, :nonexistent_key)
{:error, :not_found}
@spec name() :: String.t()
Returns the configured name of the sensor.
@spec remove_job(GenServer.server(), atom()) :: :ok | {:error, any()}
Removes a cron job by name.
@spec run_job(GenServer.server(), atom()) :: :ok | {:error, any()}
Runs a job immediately (outside its normal schedule).
@spec schema() :: Keyword.t()
Returns the configured schema for the sensor.
@spec set_config(Jido.Sensor.t(), map()) :: :ok | {:error, any()}
Updates multiple configuration values for a sensor.
Parameters
sensor
- The sensor to update. Can be a PID, atom name, or string name.config
- A map containing the configuration key-value pairs to update
Return Values
:ok
- The configuration was updated successfully{:error, reason}
- If the sensor cannot be found or accessed
Examples
iex> MySensor.set_config(sensor_pid, %{key1: "value1", key2: "value2"})
:ok
iex> MySensor.set_config(:nonexistent_sensor, %{key: "value"})
{:error, :invalid_sensor}
@spec set_config(Jido.Sensor.t(), atom(), any()) :: :ok | {:error, any()}
Updates a single configuration value for a sensor.
Parameters
sensor
- The sensor to update. Can be a PID, atom name, or string name.key
- The configuration key to updatevalue
- The new value to set
Return Values
:ok
- The configuration was updated successfully{:error, reason}
- If the sensor cannot be found or accessed
Examples
iex> MySensor.set_config(sensor_pid, :some_key, "new_value")
:ok
iex> MySensor.set_config(:nonexistent_sensor, :key, "value")
{:error, :invalid_sensor}
@spec start_link(Keyword.t()) :: GenServer.on_start()
Starts a new Sensor process.
Options
:id
(String.t/0
) - Unique identifier for the sensor instance:target
- Required. Target for signal delivery. Can be a single dispatch config tuple or a keyword list of named configurations.:retain_last
(pos_integer/0
) - Number of last values to retain The default value is10
.:scheduler
(atom/0
) - Reference to the Quantum scheduler module to use The default value isJido.Scheduler
.:jobs
(list ofterm/0
) - A list of cron jobs to be added at sensor startup. Each entry can be:- {cron_expr, task}
- {name, cron_expr, task} The default value is
[]
.
Return Values
{:ok, pid}
- The sensor was started successfully{:error, reason}
- The sensor failed to start
Examples
iex> MySensor.start_link(id: "sensor1", target: {:bus, :my_bus})
{:ok, #PID<0.123.0>}
iex> MySensor.start_link(id: "sensor1", target: {:invalid, :target})
{:error, "invalid target specification"}
@spec tags() :: [atom()]
Returns the configured tags for the sensor.
@spec to_json() :: map()
Converts the sensor metadata to a JSON-compatible map.
Returns a map containing the sensor's name, description, category, tags, version and schema configuration.
Example
iex> MySensor.to_json()
%{
name: "my_sensor",
description: "A test sensor",
category: :test,
tags: [:test, :example],
vsn: "1.0.0",
schema: []
}
@spec vsn() :: String.t() | nil
Returns the configured version of the sensor.