diff options
Diffstat (limited to 'docs/index.rst')
-rw-r--r-- | docs/index.rst | 115 |
1 files changed, 86 insertions, 29 deletions
diff --git a/docs/index.rst b/docs/index.rst index 3b49946..f69a497 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,7 +25,7 @@ Features * No (hard) external dependencies * Thread-safe API -* Excellent test coverage (tested on CPython 2.5 - 2.7, 3.3, Jython 2.5.3, PyPy 1.9) +* Excellent test coverage (tested on CPython 2.5 - 2.7, 3.2 - 3.3, Jython 2.5.3, PyPy 1.9) * Configurable scheduling mechanisms (triggers): * Cron-like scheduling @@ -34,7 +34,7 @@ Features * Multiple, simultaneously active job stores: * RAM - * File-based simple database (shelve) + * File-based simple database (:py:mod:`shelve`) * `SQLAlchemy <http://www.sqlalchemy.org/>`_ (any supported RDBMS works) * `MongoDB <http://www.mongodb.org/>`_ * `Redis <http://redis.io/>`_ @@ -46,12 +46,7 @@ Usage Installing APScheduler ---------------------- -On Python 3.3 or later (or if you have -`distutils2 <http://pypi.python.org/pypi/Distutils2>` installed) you can do:: - - $ pysetup install apscheduler - -Otherwise, you can use `pip <http://pypi.python.org/pypi/pip/>`_:: +The preferred installation method is by using `pip <http://pypi.python.org/pypi/pip/>`_:: $ pip install apscheduler @@ -128,6 +123,37 @@ running when the job is added, the job will be scheduled `tentatively` and its first run time will only be computed when the scheduler starts. Jobs will not run retroactively in such cases. +.. warning:: Scheduling new jobs from existing jobs is not currently reliable. + This will likely be fixed in the next major release. + + +.. _job_options: + +Job options +----------- + +The following options can be given as keyword arguments to +:meth:`~apscheduler.scheduler.Scheduler.add_job` or one of the shortcut +methods, including the decorators. + +===================== ========================================================= +Option Definition +===================== ========================================================= +name Name of the job (informative, does not have to be unique) +misfire_grace_time Time in seconds that the job is allowed to miss the the + designated run time before being considered to have + misfired (see :ref:`coalescing`) + (overrides the global scheduler setting) +coalesce Run once instead of many times if the scheduler + determines that the job should be run more than once in + succession (see :ref:`coalescing`) + (overrides the global scheduler setting) +max_runs Maximum number of times this job is allowed to be + triggered before being removed +max_instances Maximum number of concurrently running instances allowed + for this job (see :ref:`_max_instances`) +===================== ========================================================= + Shutting down the scheduler --------------------------- @@ -151,6 +177,15 @@ altogether:: This implies ``wait=False``, since there is no way to wait for the scheduler's tasks to finish without shutting down the thread pool. +A neat trick to automatically shut down the scheduler is to use an :py:mod:`atexit` +hook for that:: + + import atexit + + sched = Scheduler(daemon=True) + atexit.register(lambda: sched.shutdown(wait=False)) + # Proceed with starting the actual application + Scheduler configuration options ------------------------------- @@ -160,22 +195,14 @@ Directive Default Definition ======================= ========== ============================================== misfire_grace_time 1 Maximum time in seconds for the job execution to be allowed to delay before it is considered - a misfire + a misfire (see :ref:`coalescing`) coalesce False Roll several pending executions of jobs into one + (see :ref:`coalescing`) standalone False If set to ``True``, :meth:`~apscheduler.scheduler.Scheduler.start` will run the main loop in the calling - thread until no more jobs are scheduled (which - may never happen). This will naturally cause the - call to start() to block. The default setting - of ``False`` will instead spawn a new thread - to run the main loop when - :meth:`~apscheduler.scheduler.Scheduler.start` - is called. - - Set to ``False`` when the scheduler is run in - a dedicated process (as a standalone - scheduler). + thread until no more jobs are scheduled. + See :ref:`modes` for more information. daemonic True Controls whether the scheduler thread is daemonic or not. This option has no effect when ``standalone`` is ``True``. @@ -205,6 +232,27 @@ jobstores.X.Y Constructor option Y of jobstore X ======================= ========== ============================================== +.. _modes: + +Operating modes: embedded vs standalone +--------------------------------------- + +The scheduler has two operating modes: standalone and embedded. In embedded mode, +it will spawn its own thread when :meth:`~apscheduler.scheduler.Scheduler.start` +is called. In standalone mode, it will run directly in the calling thread and +will block until there are no more pending jobs. + +The embedded mode is suitable for running alongside some application that requires +scheduling capabilities. The standalone mode, on the other hand, can be used as a +handy cross-platform cron replacement for executing Python code. A typical usage +of the standalone mode is to have a script that only adds the jobs to the scheduler +and then calls :meth:`~apscheduler.scheduler.Scheduler.start` on the scheduler. + +All of the examples in the examples directory demonstrate usage of the standalone +mode, with the exception of ``threaded.py`` which demonstrates the embedded mode +(where the "application" just prints a line every 2 seconds). + + Job stores ---------- @@ -268,6 +316,8 @@ changes are never persisted back to the job store. .. note:: None of these restrictions apply to ``RAMJobStore``. +.. _max_instances: + Limiting the number of concurrently executing instances of a job ---------------------------------------------------------------- @@ -279,19 +329,26 @@ run concurrently, by using the ``max_instances`` keyword argument when adding the job. -Coalescing job executions -------------------------- +.. _coalescing: + +Missed job executions and coalescing +------------------------------------ Sometimes the scheduler may be unable to execute a scheduled job at the time it was scheduled to run. The most common case is when a job is scheduled in a persistent job store and the scheduler is shut down and restarted after the job -was supposed to execute. Normally the scheduler would execute the job as many -times as its misfire_grace_time option permits. This can be undesireable in -many cases, such as backing up data or sending notifications. By setting the -``coalesce`` option to ``True`` when adding the job (or globally on the -scheduler) you can avoid unintended successive executions of the job. The -bypassed runs of the job are not considered misfires nor do they count towards -any maximum run count of the job. +was supposed to execute. When this happens, the job is considered to have +"misfired". The scheduler will then check each missed execution time against +the job's ``misfire_grace_time`` option (which can be set on per-job basis or +globally in the scheduler) to see if the execution should still be triggered. +This can lead into the job being executed several times in succession. + +If this behavior is undesirable for your particular use case, it is possible +to use `coalescing` to roll all these missed executions into one. In other +words, if coalescing is enabled for the job and the scheduler sees one or more +queued executions for the job, it will only trigger it once. The "bypassed" +runs of the job are not considered misfires nor do they count towards any +maximum run count of the job. Scheduler events |