ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

ErisPulse-Cron

Tip

When to read this: Read this when your module needs to trigger logic at a scheduled or delayed time (such as reminders, periodic monitoring, or scheduling with Cron expressions), and you want the tasks to persist after a framework restart. Skip this if you don't need it.

ErisPulse-Cron is the scheduling module in the ErisPulse ecosystem, providing a unified API for other modules to schedule timed tasks: it supports one-time timers, interval loops, and Cron expressions, with callback parameters and SQLite persistence (tasks are not lost after a restart).

Important

Cron is not a built-in feature of the ErisPulse framework and must be installed separately:

epsdk install Cron

After installation, access all interfaces through sdk.Cron.


Feature Overview

  • Three Scheduling Types: One-time (once), interval loop (interval), and Cron expression (cron)
  • Callback Data: Pass callback_data when creating a task, and it will be returned unchanged during execution, making it easy to identify the task source
  • Persistence: Tasks are stored in SQLite (via sdk.storage), and are automatically restored after framework restart
  • Missed Trigger Strategy: Immediate execution, skip, or rescheduling, selectable per task
  • Task Management: Pause, resume, cancel, manually trigger, and clean up expired tasks
  • Dashboard Integration: Automatically registers management windows when ErisPulse-Dashboard is installed

Quick Start

from ErisPulse import sdk

# 1. Register a callback handler
@sdk.Cron.on_trigger
async def handle_trigger(info):
    data = info["callback_data"]
    print(f"Task triggered: {info['task_id']}, Data: {data}")

# 2. Create a scheduled task
task_id = sdk.Cron.once(
    delay=60,
    callback_data={"type": "reminder", "msg": "It's time to drink water"},
)

API Overview

Create Tasks

# One-time: trigger after a delay of 600 seconds
sdk.Cron.once(delay=600, callback_data={"order_id": "123"}, label="Order timeout reminder")

# Interval loop: trigger every 300 seconds, up to 100 times
sdk.Cron.interval(interval_seconds=300, callback_data={"monitor": "server-1"}, max_runs=100)

# Cron expression: trigger daily at 9:30 AM on weekdays
sdk.Cron.cron(expression="30 9 * * 1-5", callback_data={"type": "daily_report"})

# General optional parameters: trigger_at (absolute timestamp), delay (first delay), timezone,
# max_runs (0 = unlimited), label, source (module name of creator), missed_policy (missed trigger policy)

Common Cron expressions: */5 * * * * (every 5 minutes), 0 8 * * * (every day at 8 AM), 30 9 * * 1-5 (every weekday at 9:30 AM), 0 0 1 * * (every 1st day of the month).

Callback

@sdk.Cron.on_trigger
async def my_handler(info):
    # info contains task_id / task_type / callback_data / label / source /
    # run_count / max_runs / created_at / last_run / trigger_time
    ...

Multiple handlers can be registered and will be called in sequence. An exception in one handler does not affect others.

Manage Tasks

sdk.Cron.cancel(task_id)                  # Cancel
sdk.Cron.pause(task_id)                   # Pause
sdk.Cron.resume(task_id)                  # Resume (reschedule=True recalculates next trigger time)
await sdk.Cron.trigger_now(task_id)       # Manually trigger immediately (does not affect original schedule)
sdk.Cron.get_task(task_id)                # View a single task
sdk.Cron.list_tasks(source="MyModule")    # List tasks (supports filtering by source/status/task_type)
sdk.Cron.delete_task(task_id)             # Delete task record
sdk.Cron.cleanup()                        # Clean up completed/canceled tasks older than 7 days

Missed Policy (missed_policy)

When the framework restarts, for tasks that missed their trigger time:

Policy Behavior
fire_immediately Trigger immediately (default)
skip Skip this trigger, wait for the next one
reschedule Recalculate the next trigger time from the current time

Behavior on Module Unload

Cron's task data is a persistent asset: unloading or disabling the module that created the task does not delete the created task. However, the callback handles registered by the module will be cleaned up. Based on the ownership system's external cleanup hooks, Cron automatically names callbacks it manages on behalf of other modules. When the corresponding module is unloaded or disabled, its callback handles are automatically discarded, ensuring that the module instance can be properly reclaimed.

  • After the task creator module is reloaded, re-registering on_trigger resumes receiving triggers.
  • Tasks that are no longer needed can be cleaned up using sdk.Cron.cancel(task_id) / delete_task(task_id).

Next Steps

  • Send message to user after task trigger: Use Send DSL or event.reply() (see Event System API) in the callback to deliver the reminder.
  • Visually manage scheduled tasks: After installing ErisPulse-Dashboard, a Cron auto-registration management window will be available.
  • Callback cleanup details when module is uninstalled: Ownership system