← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.2-docs-html/_sources/library/sched.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-3.5.2-docs-html/_sources/library/sched.txt
 
1
:mod:`sched` --- Event scheduler
 
2
================================
 
3
 
 
4
.. module:: sched
 
5
   :synopsis: General purpose event scheduler.
 
6
 
 
7
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
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). If time.monotonic is not available, the *timefunc* default
 
24
   is time.time instead. The *delayfunc* function should be callable with one
 
25
   argument, compatible with the output of *timefunc*, and should delay that many
 
26
   time units. *delayfunc* will also be called with the argument ``0`` after each
 
27
   event is run to allow other threads an opportunity to run in multi-threaded
 
28
   applications.
 
29
 
 
30
   .. versionchanged:: 3.3
 
31
      *timefunc* and *delayfunc* parameters are optional.
 
32
 
 
33
   .. versionchanged:: 3.3
 
34
      :class:`scheduler` class can be safely used in multi-threaded
 
35
      environments.
 
36
 
 
37
Example::
 
38
 
 
39
   >>> import sched, time
 
40
   >>> s = sched.scheduler(time.time, time.sleep)
 
41
   >>> def print_time(a='default'):
 
42
   ...     print("From print_time", time.time(), a)
 
43
   ...
 
44
   >>> def print_some_times():
 
45
   ...     print(time.time())
 
46
   ...     s.enter(10, 1, print_time)
 
47
   ...     s.enter(5, 2, print_time, argument=('positional',))
 
48
   ...     s.enter(5, 1, print_time, kwargs={'a': 'keyword'})
 
49
   ...     s.run()
 
50
   ...     print(time.time())
 
51
   ...
 
52
   >>> print_some_times()
 
53
   930343690.257
 
54
   From print_time 930343695.274 positional
 
55
   From print_time 930343695.275 keyword
 
56
   From print_time 930343700.273 default
 
57
   930343700.276
 
58
 
 
59
.. _scheduler-objects:
 
60
 
 
61
Scheduler Objects
 
62
-----------------
 
63
 
 
64
:class:`scheduler` instances have the following methods and attributes:
 
65
 
 
66
 
 
67
.. method:: scheduler.enterabs(time, priority, action, argument=(), kwargs={})
 
68
 
 
69
   Schedule a new event. The *time* argument should be a numeric type compatible
 
70
   with the return value of the *timefunc* function passed  to the constructor.
 
71
   Events scheduled for the same *time* will be executed in the order of their
 
72
   *priority*.
 
73
 
 
74
   Executing the event means executing ``action(*argument, **kwargs)``.
 
75
   *argument* is a sequence holding the positional arguments for *action*.
 
76
   *kwargs* is a dictionary holding the keyword arguments for *action*.
 
77
 
 
78
   Return value is an event which may be used for later cancellation of the event
 
79
   (see :meth:`cancel`).
 
80
 
 
81
   .. versionchanged:: 3.3
 
82
      *argument* parameter is optional.
 
83
 
 
84
   .. versionadded:: 3.3
 
85
      *kwargs* parameter was added.
 
86
 
 
87
 
 
88
.. method:: scheduler.enter(delay, priority, action, argument=(), kwargs={})
 
89
 
 
90
   Schedule an event for *delay* more time units. Other than the relative time, the
 
91
   other arguments, the effect and the return value are the same as those for
 
92
   :meth:`enterabs`.
 
93
 
 
94
   .. versionchanged:: 3.3
 
95
      *argument* parameter is optional.
 
96
 
 
97
   .. versionadded:: 3.3
 
98
      *kwargs* parameter was added.
 
99
 
 
100
.. method:: scheduler.cancel(event)
 
101
 
 
102
   Remove the event from the queue. If *event* is not an event currently in the
 
103
   queue, this method will raise a :exc:`ValueError`.
 
104
 
 
105
 
 
106
.. method:: scheduler.empty()
 
107
 
 
108
   Return true if the event queue is empty.
 
109
 
 
110
 
 
111
.. method:: scheduler.run(blocking=True)
 
112
 
 
113
   Run all scheduled events. This method will wait  (using the :func:`delayfunc`
 
114
   function passed to the constructor) for the next event, then execute it and so
 
115
   on until there are no more scheduled events.
 
116
 
 
117
   If *blocking* is false executes the scheduled events due to expire soonest
 
118
   (if any) and then return the deadline of the next scheduled call in the
 
119
   scheduler (if any).
 
120
 
 
121
   Either *action* or *delayfunc* can raise an exception.  In either case, the
 
122
   scheduler will maintain a consistent state and propagate the exception.  If an
 
123
   exception is raised by *action*, the event will not be attempted in future calls
 
124
   to :meth:`run`.
 
125
 
 
126
   If a sequence of events takes longer to run than the time available before the
 
127
   next event, the scheduler will simply fall behind.  No events will be dropped;
 
128
   the calling code is responsible for canceling  events which are no longer
 
129
   pertinent.
 
130
 
 
131
   .. versionadded:: 3.3
 
132
      *blocking* parameter was added.
 
133
 
 
134
.. attribute:: scheduler.queue
 
135
 
 
136
   Read-only attribute returning a list of upcoming events in the order they
 
137
   will be run.  Each event is shown as a :term:`named tuple` with the
 
138
   following fields:  time, priority, action, argument, kwargs.