From 6c57dca57a6842f3980bb8cdce77bdf852948c09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Gr=C3=B6nholm?= Date: Sun, 4 Sep 2022 19:26:08 +0300 Subject: Added section to user guide on how to run the scheduler --- docs/userguide.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/docs/userguide.rst b/docs/userguide.rst index 46108d1..f9f1b50 100644 --- a/docs/userguide.rst +++ b/docs/userguide.rst @@ -79,6 +79,88 @@ An *event broker* delivers published events to all interested parties. It facili the cooperation between schedulers and workers by notifying them of new or updated schedules or jobs. +Running the scheduler +===================== + +The scheduler can run either in the foreground, blocking on a call to +:meth:`~apscheduler.schedulers.sync.Scheduler.run_until_complete`, or in the background +where it does its work while letting the rest of the program run. + +If the only intent of your program is to run scheduled tasks, then you should start the +scheduler with :meth:`~apscheduler.schedulers.sync.Scheduler.run_until_complete`. But if +you need to do other things too, then you should call +:meth:`~apscheduler.schedulers.sync.Scheduler.start_in_background` before running the +rest of the program. + +The scheduler can be used as a context manager. This initializes the underlying data +store and event broker, allowing you to use the scheduler for manipulating tasks and +schedules prior to actually starting it. Exiting the context manager will shut down +the scheduler and its underlying services. This mode of operation is mandatory for the +asynchronous scheduler when running it in the background, but it is preferred for the +synchronous scheduler too. + +As a special consideration (for use with WSGI_ based web frameworks), the synchronous +scheduler can be run in the background without being used as a context manager. In this +scenario, the scheduler adds an :mod:`atexit` hook that will perform an orderly shutdown +of the scheduler before the process terminates. + +.. _WSGI: https://wsgi.readthedocs.io/en/latest/what.html + +.. warning:: If you start the scheduler in the background and let the script finish + execution, the scheduler will automatically shut down as well. + +.. tabs:: + + .. code-tab:: python Synchronous (run in foreground) + + from apscheduler.schedulers.sync import Scheduler + + scheduler = Scheduler() + # Add schedules, configure tasks here + scheduler.run_until_stopped() + + .. code-tab:: python Synchronous (background thread; preferred method) + + from apscheduler.schedulers.sync import Scheduler + + with Scheduler() as scheduler: + # Add schedules, configure tasks here + scheduler.start_in_background() + + .. code-tab:: python Synchronous (background thread; WSGI alternative) + + from apscheduler.schedulers.sync import Scheduler + + scheduler = Scheduler() + # Add schedules, configure tasks here + scheduler.start_in_background() + + .. code-tab:: python Asynchronous (run in foreground) + + import asyncio + + from apscheduler.schedulers.async_ import AsyncScheduler + + async def main(): + async with AsyncScheduler() as scheduler: + # Add schedules, configure tasks here + await scheduler.run_until_stopped() + + asyncio.run(main()) + + .. code-tab:: python Asynchronous (background task) + + import asyncio + + from apscheduler.schedulers.async_ import AsyncScheduler + + async def main(): + async with AsyncScheduler() as scheduler: + # Add schedules, configure tasks here + await scheduler.start_in_background() + + asyncio.run(main()) + Scheduling tasks ================ -- cgit v1.2.1