ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

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)