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