ErisPulse-Cron
Tip
Когда стоит читать этот документ: когда вашему модулю требуется логика запуска по расписанию или с задержкой (напоминания по расписанию, периодический мониторинг, планирование по Cron-выражениям), и вы хотите, чтобы задачи не терялись после перезапуска фреймворка. Если это не ваш случай — пропустите.
ErisPulse-Cron — это модуль планирования задач по расписанию в экосистеме ErisPulse, предоставляющий другим модулям единый API для работы с отложенными задачами: поддерживает три типа задач — однократный запуск по времени, циклический запуск с интервалом и Cron-выражения, передачу параметров в колбэки, а также персистентность в SQLite (задачи не теряются после перезапуска).
Important
Cron не является встроенной функциональностью фреймворка ErisPulse и требует отдельной установки:
epsdk install Cron
После установки весь API доступен через sdk.Cron.
Краткий обзор возможностей
- Три типа расписания: однократный запуск (
once), циклический запуск с интервалом (interval), Cron-выражения (cron) - Передача параметров в колбэки: при создании передаётся
callback_data, которая при срабатывании возвращается без изменений — это удобно для определения источника задачи - Персистентность: задачи хранятся в SQLite (через
sdk.storage) и автоматически восстанавливаются после перезапуска фреймворка - Политика пропущенных запусков: немедленный запуск / пропуск / перепланирование — выбирается отдельно для каждой задачи
- Управление задачами: пауза, возобновление, отмена, ручной запуск, очистка устаревших задач
- Интеграция с Dashboard: при установленном ErisPulse-Dashboard панель управления регистрируется автоматически
Быстрый старт
from ErisPulse import sdk
# 1. Регистрация обработчика колбэка
@sdk.Cron.on_trigger
async def handle_trigger(info):
data = info["callback_data"]
print(f"Задача сработала: {info['task_id']}, данные: {data}")
# 2. Создание задачи по расписанию
task_id = sdk.Cron.once(
delay=60,
callback_data={"type": "reminder", "msg": "Пора попить воды"},
)
Обзор API
Создание задач
# Однократная задача: срабатывает с задержкой 600 секунд
sdk.Cron.once(delay=600, callback_data={"order_id": "123"}, label="Напоминание о таймауте заказа")
# Циклическая задача: срабатывает каждые 300 секунд, максимум 100 раз
sdk.Cron.interval(interval_seconds=300, callback_data={"monitor": "server-1"}, max_runs=100)
# Cron-выражение: по будням каждый день в 9:30
sdk.Cron.cron(expression="30 9 * * 1-5", callback_data={"type": "daily_report"})
# Общие необязательные параметры: trigger_at (абсолютная временная метка), delay (задержка первого запуска), timezone,
# max_runs (0=бесконечно), label, source (имя модуля-создателя), missed_policy (политика пропущенных запусков)
Распространённые Cron-выражения: */5 * * * * (каждые 5 минут), 0 8 * * * (каждый день в 8 утра), 30 9 * * 1-5 (по будням в 9:30), 0 0 1 * * (1-го числа каждого месяца).
Колбэки
@sdk.Cron.on_trigger
async def my_handler(info):
# info содержит task_id / task_type / callback_data / label / source /
# run_count / max_runs / created_at / last_run / trigger_time
...
Поддерживается регистрация нескольких обработчиков (handler); все они вызываются по очереди, и исключение в одном из них не влияет на работу остальных.
Управление задачами
sdk.Cron.cancel(task_id) # Отмена
sdk.Cron.pause(task_id) # Пауза
sdk.Cron.resume(task_id) # Возобновление (reschedule=True пересчитывает время следующего запуска)
await sdk.Cron.trigger_now(task_id) # Ручной немедленный запуск (не влияет на исходное расписание)
sdk.Cron.get_task(task_id) # Просмотр отдельной задачи
sdk.Cron.list_tasks(source="MyModule") # Список задач (поддерживается фильтрация по source/status/task_type)
sdk.Cron.delete_task(task_id) # Удаление записи задачи
sdk.Cron.cleanup() # Очистка выполненных/отменённых задач старше 7 дней
Политика пропущенных запусков (missed_policy)
После перезапуска фреймворка для задач, у которых было пропущено время срабатывания:
| Политика | Поведение |
|---|---|
fire_immediately |
Немедленный запуск (по умолчанию) |
skip |
Пропустить текущий запуск и ждать следующего |
reschedule |
Пересчитать время следующего запуска от текущего момента |
Поведение при выгрузке модуля
Данные задач Cron являются персистентным активом: выгрузка или отключение модуля-создателя задачи не приводит к удалению уже созданных задач. Однако зарегистрированные этим модулем обработчики колбэков будут очищены — благодаря хукам внешней очистки на основе системы владения, Cron при хранении колбэков от имени других модулей автоматически фиксирует их владельца, и при выгрузке/отключении модуля-владельца его обработчики колбэков автоматически отбрасываются, что гарантирует корректную утилизацию экземпляров этого модуля.
- После перезагрузки модуля-создателя достаточно заново зарегистрировать
on_trigger, чтобы восстановить приём срабатываний - Ненужные задачи можно очистить с помощью
sdk.Cron.cancel(task_id)/delete_task(task_id)
Полезные ссылки
Следующие шаги
- Отправка сообщений пользователю после срабатывания задачи: в колбэке используйте Send DSL или
event.reply()(см. API системы событий) для доставки напоминания - Визуальное управление задачами по расписанию: после установки ErisPulse-Dashboard Cron автоматически регистрирует панель управления
- Детали очистки колбэков при выгрузке модуля: система владения (owner)