Debian Codegraph @

Doc/library/sched.rst

raw
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, immediately executes all events in the queue which have
123 a time value less than or equal to the current *timefunc* value (if any) and
124 returns the difference between the current *timefunc* value and the time value
125 of the next scheduled event in the scheduler's event queue. If the queue is
126 empty, returns ``None``.
127
128 Either *action* or *delayfunc* can raise an exception. In either case, the
129 scheduler will maintain a consistent state and propagate the exception. If an
130 exception is raised by *action*, the event will not be attempted in future calls
131 to :meth:`run`.
132
133 If a sequence of events takes longer to run than the time available before the
134 next event, the scheduler will simply fall behind. No events will be dropped;
135 the calling code is responsible for canceling events which are no longer
136 pertinent.
137
138 .. versionchanged:: 3.3
139 *blocking* parameter was added.
140
141 .. attribute:: scheduler.queue
142
143 Read-only attribute returning a list of upcoming events in the order they
144 will be run. Each event is shown as a :term:`named tuple` with the
145 following fields: time, priority, action, argument, kwargs.