Jido.Sensors.Cron (Jido v1.2.0)

View Source

A 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

sensor_result()

@type sensor_result() :: Jido.Sensor.sensor_result()

t()

@type t() :: Jido.Sensor.t()

Functions

activate_job(sensor, name)

@spec activate_job(GenServer.server(), atom()) :: :ok | {:error, any()}

Activates a cron job by name.

add_job(sensor, name, schedule, task)

@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.

category()

@spec category() :: atom() | nil

Returns the configured category of the sensor.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

deactivate_job(sensor, name)

@spec deactivate_job(GenServer.server(), atom()) :: :ok | {:error, any()}

Deactivates a cron job by name.

description()

@spec description() :: String.t() | nil

Returns the configured description of the sensor.

get_config(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}

get_config(sensor, key)

@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}

name()

@spec name() :: String.t()

Returns the configured name of the sensor.

remove_job(sensor, name)

@spec remove_job(GenServer.server(), atom()) :: :ok | {:error, any()}

Removes a cron job by name.

run_job(sensor, name)

@spec run_job(GenServer.server(), atom()) :: :ok | {:error, any()}

Runs a job immediately (outside its normal schedule).

schema()

@spec schema() :: Keyword.t()

Returns the configured schema for the sensor.

set_config(sensor, config)

@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}

set_config(sensor, key, value)

@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 update
  • value - 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}

start_link(opts)

@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 is 10.

  • :scheduler (atom/0) - Reference to the Quantum scheduler module to use The default value is Jido.Scheduler.

  • :jobs (list of term/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"}

tags()

@spec tags() :: [atom()]

Returns the configured tags for the sensor.

to_json()

@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: []
}

vsn()

@spec vsn() :: String.t() | nil

Returns the configured version of the sensor.