summaryrefslogtreecommitdiffstats
path: root/Doc/library/sched.rst
blob: f1a376fc25024c9ce47816c7710be62436c9f7a7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
:mod:`sched` --- Event scheduler
================================

.. module:: sched
   :synopsis: General purpose event scheduler.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>

.. index:: single: event scheduling

**Source code:** :source:`Lib/sched.py`

--------------

The :mod:`sched` module defines a class which implements a general purpose event
scheduler:

.. class:: scheduler(timefunc=time.monotonic, delayfunc=time.sleep)

   The :class:`scheduler` class defines a generic interface to scheduling events.
   It needs two functions to actually deal with the "outside world" --- *timefunc*
   should be callable without arguments, and return  a number (the "time", in any
   units whatsoever). If time.monotonic is not available, the *timefunc* default
   is time.time instead. The *delayfunc* function should be callable with one
   argument, compatible with the output of *timefunc*, and should delay that many
   time units. *delayfunc* will also be called with the argument ``0`` after each
   event is run to allow other threads an opportunity to run in multi-threaded
   applications.

   .. versionchanged:: 3.3
      *timefunc* and *delayfunc* parameters are optional.

   .. versionchanged:: 3.3
      :class:`scheduler` class can be safely used in multi-threaded
      environments.

Example::

   >>> import sched, time
   >>> s = sched.scheduler(time.time, time.sleep)
   >>> def print_time(a='default'):
   ...     print("From print_time", time.time(), a)
   ...
   >>> def print_some_times():
   ...     print(time.time())
   ...     s.enter(10, 1, print_time)
   ...     s.enter(5, 2, print_time, argument=('positional',))
   ...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
   ...     s.run()
   ...     print(time.time())
   ...
   >>> print_some_times()
   930343690.257
   From print_time 930343695.274 positional
   From print_time 930343695.275 keyword
   From print_time 930343700.273 default
   930343700.276

.. _scheduler-objects:

Scheduler Objects
-----------------

:class:`scheduler` instances have the following methods and attributes:


.. method:: scheduler.enterabs(time, priority, action, argument=(), kwargs={})

   Schedule a new event. The *time* argument should be a numeric type compatible
   with the return value of the *timefunc* function passed  to the constructor.
   Events scheduled for the same *time* will be executed in the order of their
   *priority*.

   Executing the event means executing ``action(*argument, **kwargs)``.
   *argument* is a sequence holding the positional arguments for *action*.
   *kwargs* is a dictionary holding the keyword arguments for *action*.

   Return value is an event which may be used for later cancellation of the event
   (see :meth:`cancel`).

   .. versionchanged:: 3.3
      *argument* parameter is optional.

   .. versionadded:: 3.3
      *kwargs* parameter was added.


.. method:: scheduler.enter(delay, priority, action, argument=(), kwargs={})

   Schedule an event for *delay* more time units. Other than the relative time, the
   other arguments, the effect and the return value are the same as those for
   :meth:`enterabs`.

   .. versionchanged:: 3.3
      *argument* parameter is optional.

   .. versionadded:: 3.3
      *kwargs* parameter was added.

.. method:: scheduler.cancel(event)

   Remove the event from the queue. If *event* is not an event currently in the
   queue, this method will raise a :exc:`ValueError`.


.. method:: scheduler.empty()

   Return true if the event queue is empty.


.. method:: scheduler.run(blocking=True)

   Run all scheduled events. This method will wait  (using the :func:`delayfunc`
   function passed to the constructor) for the next event, then execute it and so
   on until there are no more scheduled events.

   If *blocking* is False executes the scheduled events due to expire soonest
   (if any) and then return the deadline of the next scheduled call in the
   scheduler (if any).

   Either *action* or *delayfunc* can raise an exception.  In either case, the
   scheduler will maintain a consistent state and propagate the exception.  If an
   exception is raised by *action*, the event will not be attempted in future calls
   to :meth:`run`.

   If a sequence of events takes longer to run than the time available before the
   next event, the scheduler will simply fall behind.  No events will be dropped;
   the calling code is responsible for canceling  events which are no longer
   pertinent.

   .. versionadded:: 3.3
      *blocking* parameter was added.

.. attribute:: scheduler.queue

   Read-only attribute returning a list of upcoming events in the order they
   will be run.  Each event is shown as a :term:`named tuple` with the
   following fields:  time, priority, action, argument, kwargs.