| 1 |
:mod:`!sched` --- Event scheduler |
| 2 |
================================= |
| 3 |
|
| 4 |
.. module:: sched |
| 5 |
:synopsis: General purpose event scheduler. |
| 6 |
|
| 7 |
.. sectionauthor:: Moshe Zadka <[email protected]> |
| 8 |
|
| 9 |
**Source code:** :source:`Lib/sched.py` |
| 10 |
|
| 11 |
.. index:: single: event scheduling |
| 12 |
|
| 13 |
-------------- |
| 14 |
|
| 15 |
The :mod:`!sched` module defines a class which implements a general purpose event |
| 16 |
scheduler: |
| 17 |
|
| 18 |
.. class:: scheduler(timefunc=time.monotonic, delayfunc=time.sleep) |
| 19 |
|
| 20 |
The :class:`scheduler` class defines a generic interface to scheduling events. |
| 21 |
It needs two functions to actually deal with the "outside world" --- *timefunc* |
| 22 |
should be callable without arguments, and return a number (the "time", in any |
| 23 |
units whatsoever). The *delayfunc* function should be callable with one |
| 24 |
argument, compatible with the output of *timefunc*, and should delay that many |
| 25 |
time units. *delayfunc* will also be called with the argument ``0`` after each |
| 26 |
event is run to allow other threads an opportunity to run in multi-threaded |
| 27 |
applications. |
| 28 |
|
| 29 |
.. versionchanged:: 3.3 |
| 30 |
*timefunc* and *delayfunc* parameters are optional. |
| 31 |
|
| 32 |
.. versionchanged:: 3.3 |
| 33 |
:class:`scheduler` class can be safely used in multi-threaded |
| 34 |
environments. |
| 35 |
|
| 36 |
Example:: |
| 37 |
|
| 38 |
>>> import sched, time |
| 39 |
>>> s = sched.scheduler(time.time, time.sleep) |
| 40 |
>>> def print_time(a='default'): |
| 41 |
... print("From print_time", time.time(), a) |
| 42 |
... |
| 43 |
>>> def print_some_times(): |
| 44 |
... print(time.time()) |
| 45 |
... s.enter(10, 1, print_time) |
| 46 |
... s.enter(5, 2, print_time, argument=('positional',)) |
| 47 |
... # despite having higher priority, 'keyword' runs after 'positional' as enter() is relative |
| 48 |
... s.enter(5, 1, print_time, kwargs={'a': 'keyword'}) |
| 49 |
... s.enterabs(1_650_000_000, 10, print_time, argument=("first enterabs",)) |
| 50 |
... s.enterabs(1_650_000_000, 5, print_time, argument=("second enterabs",)) |
| 51 |
... s.run() |
| 52 |
... print(time.time()) |
| 53 |
... |
| 54 |
>>> print_some_times() |
| 55 |
1652342830.3640375 |
| 56 |
From print_time 1652342830.3642538 second enterabs |
| 57 |
From print_time 1652342830.3643398 first enterabs |
| 58 |
From print_time 1652342835.3694863 positional |
| 59 |
From print_time 1652342835.3696074 keyword |
| 60 |
From print_time 1652342840.369612 default |
| 61 |
1652342840.3697174 |
| 62 |
|
| 63 |
|
| 64 |
.. _scheduler-objects: |
| 65 |
|
| 66 |
Scheduler Objects |
| 67 |
----------------- |
| 68 |
|
| 69 |
:class:`scheduler` instances have the following methods and attributes: |
| 70 |
|
| 71 |
|
| 72 |
.. method:: scheduler.enterabs(time, priority, action, argument=(), kwargs={}) |
| 73 |
|
| 74 |
Schedule a new event. The *time* argument should be a numeric type compatible |
| 75 |
with the return value of the *timefunc* function passed to the constructor. |
| 76 |
Events scheduled for the same *time* will be executed in the order of their |
| 77 |
*priority*. A lower number represents a higher priority. |
| 78 |
|
| 79 |
Executing the event means executing ``action(*argument, **kwargs)``. |
| 80 |
*argument* is a sequence holding the positional arguments for *action*. |
| 81 |
*kwargs* is a dictionary holding the keyword arguments for *action*. |
| 82 |
|
| 83 |
Return value is an event which may be used for later cancellation of the event |
| 84 |
(see :meth:`cancel`). |
| 85 |
|
| 86 |
.. versionchanged:: 3.3 |
| 87 |
*argument* parameter is optional. |
| 88 |
|
| 89 |
.. versionchanged:: 3.3 |
| 90 |
*kwargs* parameter was added. |
| 91 |
|
| 92 |
|
| 93 |
.. method:: scheduler.enter(delay, priority, action, argument=(), kwargs={}) |
| 94 |
|
| 95 |
Schedule an event for *delay* more time units. Other than the relative time, the |
| 96 |
other arguments, the effect and the return value are the same as those for |
| 97 |
:meth:`enterabs`. |
| 98 |
|
| 99 |
.. versionchanged:: 3.3 |
| 100 |
*argument* parameter is optional. |
| 101 |
|
| 102 |
.. versionchanged:: 3.3 |
| 103 |
*kwargs* parameter was added. |
| 104 |
|
| 105 |
.. method:: scheduler.cancel(event) |
| 106 |
|
| 107 |
Remove the event from the queue. If *event* is not an event currently in the |
| 108 |
queue, this method will raise a :exc:`ValueError`. |
| 109 |
|
| 110 |
|
| 111 |
.. method:: scheduler.empty() |
| 112 |
|
| 113 |
Return ``True`` if the event queue is empty. |
| 114 |
|
| 115 |
|
| 116 |
.. method:: scheduler.run(blocking=True) |
| 117 |
|
| 118 |
Run all scheduled events. This method will wait (using the *delayfunc* |
| 119 |
function passed to the constructor) for the next event, then execute it and so |
| 120 |
on until there are no more scheduled events. |
| 121 |
|
| 122 |
If *blocking* is false executes the scheduled events due to expire soonest |
| 123 |
(if any) and then return the deadline of the next scheduled call in the |
| 124 |
scheduler (if any). |
| 125 |
|
| 126 |
Either *action* or *delayfunc* can raise an exception. In either case, the |
| 127 |
scheduler will maintain a consistent state and propagate the exception. If an |
| 128 |
exception is raised by *action*, the event will not be attempted in future calls |
| 129 |
to :meth:`run`. |
| 130 |
|
| 131 |
If a sequence of events takes longer to run than the time available before the |
| 132 |
next event, the scheduler will simply fall behind. No events will be dropped; |
| 133 |
the calling code is responsible for canceling events which are no longer |
| 134 |
pertinent. |
| 135 |
|
| 136 |
.. versionchanged:: 3.3 |
| 137 |
*blocking* parameter was added. |
| 138 |
|
| 139 |
.. attribute:: scheduler.queue |
| 140 |
|
| 141 |
Read-only attribute returning a list of upcoming events in the order they |
| 142 |
will be run. Each event is shown as a :term:`named tuple` with the |
| 143 |
following fields: time, priority, action, argument, kwargs. |