blob: a76aacc9f835503d8d99f1fd99847b07d6beb2fb [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001: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
Georg Brandl116aa622007-08-15 14:28:22 +00008.. index:: single: event scheduling
9
Raymond Hettinger10480942011-01-10 03:26:08 +000010**Source code:** :source:`Lib/sched.py`
11
Georg Brandl116aa622007-08-15 14:28:22 +000012The :mod:`sched` module defines a class which implements a general purpose event
13scheduler:
14
Georg Brandl116aa622007-08-15 14:28:22 +000015.. class:: scheduler(timefunc, delayfunc)
16
17 The :class:`scheduler` class defines a generic interface to scheduling events.
18 It needs two functions to actually deal with the "outside world" --- *timefunc*
19 should be callable without arguments, and return a number (the "time", in any
20 units whatsoever). The *delayfunc* function should be callable with one
21 argument, compatible with the output of *timefunc*, and should delay that many
22 time units. *delayfunc* will also be called with the argument ``0`` after each
23 event is run to allow other threads an opportunity to run in multi-threaded
24 applications.
25
26Example::
27
28 >>> import sched, time
Christian Heimesfe337bf2008-03-23 21:54:12 +000029 >>> s = sched.scheduler(time.time, time.sleep)
Georg Brandl6911e3c2007-09-04 07:15:32 +000030 >>> def print_time(): print("From print_time", time.time())
Georg Brandl116aa622007-08-15 14:28:22 +000031 ...
32 >>> def print_some_times():
Georg Brandl6911e3c2007-09-04 07:15:32 +000033 ... print(time.time())
Georg Brandl116aa622007-08-15 14:28:22 +000034 ... s.enter(5, 1, print_time, ())
35 ... s.enter(10, 1, print_time, ())
36 ... s.run()
Georg Brandl6911e3c2007-09-04 07:15:32 +000037 ... print(time.time())
Georg Brandl116aa622007-08-15 14:28:22 +000038 ...
39 >>> print_some_times()
40 930343690.257
41 From print_time 930343695.274
42 From print_time 930343700.273
43 930343700.276
44
Christian Heimes679db4a2008-01-18 09:56:22 +000045In multi-threaded environments, the :class:`scheduler` class has limitations
Georg Brandl48310cd2009-01-03 21:18:54 +000046with respect to thread-safety, inability to insert a new task before
Christian Heimes679db4a2008-01-18 09:56:22 +000047the one currently pending in a running scheduler, and holding up the main
48thread until the event queue is empty. Instead, the preferred approach
49is to use the :class:`threading.Timer` class instead.
50
51Example::
52
53 >>> import time
54 >>> from threading import Timer
55 >>> def print_time():
Neal Norwitz752abd02008-05-13 04:55:24 +000056 ... print("From print_time", time.time())
Christian Heimes679db4a2008-01-18 09:56:22 +000057 ...
58 >>> def print_some_times():
Neal Norwitz752abd02008-05-13 04:55:24 +000059 ... print(time.time())
Christian Heimes679db4a2008-01-18 09:56:22 +000060 ... Timer(5, print_time, ()).start()
61 ... Timer(10, print_time, ()).start()
Georg Brandla1c6a1c2009-01-03 21:26:05 +000062 ... time.sleep(11) # sleep while time-delay events execute
Neal Norwitz752abd02008-05-13 04:55:24 +000063 ... print(time.time())
Christian Heimes679db4a2008-01-18 09:56:22 +000064 ...
65 >>> print_some_times()
66 930343690.257
67 From print_time 930343695.274
68 From print_time 930343700.273
69 930343701.301
70
Georg Brandl116aa622007-08-15 14:28:22 +000071
72.. _scheduler-objects:
73
74Scheduler Objects
75-----------------
76
Christian Heimes679db4a2008-01-18 09:56:22 +000077:class:`scheduler` instances have the following methods and attributes:
Georg Brandl116aa622007-08-15 14:28:22 +000078
79
80.. method:: scheduler.enterabs(time, priority, action, argument)
81
82 Schedule a new event. The *time* argument should be a numeric type compatible
83 with the return value of the *timefunc* function passed to the constructor.
84 Events scheduled for the same *time* will be executed in the order of their
85 *priority*.
86
87 Executing the event means executing ``action(*argument)``. *argument* must be a
88 sequence holding the parameters for *action*.
89
90 Return value is an event which may be used for later cancellation of the event
91 (see :meth:`cancel`).
92
93
94.. method:: scheduler.enter(delay, priority, action, argument)
95
96 Schedule an event for *delay* more time units. Other then the relative time, the
97 other arguments, the effect and the return value are the same as those for
98 :meth:`enterabs`.
99
100
101.. method:: scheduler.cancel(event)
102
103 Remove the event from the queue. If *event* is not an event currently in the
Georg Brandlc38a0002009-05-26 07:51:03 +0000104 queue, this method will raise a :exc:`ValueError`.
Georg Brandl116aa622007-08-15 14:28:22 +0000105
106
107.. method:: scheduler.empty()
108
109 Return true if the event queue is empty.
110
111
112.. method:: scheduler.run()
113
114 Run all scheduled events. This function will wait (using the :func:`delayfunc`
115 function passed to the constructor) for the next event, then execute it and so
116 on until there are no more scheduled events.
117
118 Either *action* or *delayfunc* can raise an exception. In either case, the
119 scheduler will maintain a consistent state and propagate the exception. If an
120 exception is raised by *action*, the event will not be attempted in future calls
121 to :meth:`run`.
122
123 If a sequence of events takes longer to run than the time available before the
124 next event, the scheduler will simply fall behind. No events will be dropped;
125 the calling code is responsible for canceling events which are no longer
126 pertinent.
127
Christian Heimes679db4a2008-01-18 09:56:22 +0000128.. attribute:: scheduler.queue
129
130 Read-only attribute returning a list of upcoming events in the order they
131 will be run. Each event is shown as a :term:`named tuple` with the
132 following fields: time, priority, action, argument.