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 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.