rest25/library/sched.rst => rest262/library/sched.rst
n1- 
2:mod:`sched` --- Event scheduler
3================================
4
5.. module:: sched
6   :synopsis: General purpose event scheduler.
7.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
n8- 
9- 
10-.. % LaTeXed and enhanced from comments in file
11
12.. index:: single: event scheduling
13
14The :mod:`sched` module defines a class which implements a general purpose event
15scheduler:
16
17
18.. class:: scheduler(timefunc, delayfunc)
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
29Example::
30
31   >>> import sched, time
n32-   >>> s=sched.scheduler(time.time, time.sleep)
n28+   >>> s = sched.scheduler(time.time, time.sleep)
33   >>> def print_time(): print "From print_time", time.time()
34   ...
35   >>> def print_some_times():
36   ...     print time.time()
37   ...     s.enter(5, 1, print_time, ())
38   ...     s.enter(10, 1, print_time, ())
39   ...     s.run()
40   ...     print time.time()
41   ...
42   >>> print_some_times()
43   930343690.257
44   From print_time 930343695.274
45   From print_time 930343700.273
46   930343700.276
47
n44+In multi-threaded environments, the :class:`scheduler` class has limitations
45+with respect to thread-safety, inability to insert a new task before
46+the one currently pending in a running scheduler, and holding up the main
47+thread until the event queue is empty.  Instead, the preferred approach
48+is to use the :class:`threading.Timer` class instead.
49+ 
50+Example::
51+ 
52+    >>> import time
53+    >>> from threading import Timer
54+    >>> def print_time():
55+    ...     print "From print_time", time.time()
56+    ...
57+    >>> def print_some_times():
58+    ...     print time.time()
59+    ...     Timer(5, print_time, ()).start()
60+    ...     Timer(10, print_time, ()).start()
61+    ...     time.sleep(11)  # sleep while time-delay events execute
62+    ...     print time.time()
63+    ...
64+    >>> print_some_times()
65+    930343690.257
66+    From print_time 930343695.274
67+    From print_time 930343700.273
68+    930343701.301
69+ 
48
49.. _scheduler-objects:
50
51Scheduler Objects
52-----------------
53
n54-:class:`scheduler` instances have the following methods:
n76+:class:`scheduler` instances have the following methods and attributes:
55
56
n57-.. method:: XXX Class.enterabs(time, priority, action, argument)
n79+.. method:: scheduler.enterabs(time, priority, action, argument)
58
59   Schedule a new event. The *time* argument should be a numeric type compatible
60   with the return value of the *timefunc* function passed  to the constructor.
61   Events scheduled for the same *time* will be executed in the order of their
62   *priority*.
63
64   Executing the event means executing ``action(*argument)``.  *argument* must be a
65   sequence holding the parameters for *action*.
66
67   Return value is an event which may be used for later cancellation of the event
68   (see :meth:`cancel`).
69
70
n71-.. method:: XXX Class.enter(delay, priority, action, argument)
n93+.. method:: scheduler.enter(delay, priority, action, argument)
72
73   Schedule an event for *delay* more time units. Other then the relative time, the
74   other arguments, the effect and the return value are the same as those for
75   :meth:`enterabs`.
76
77
n78-.. method:: XXX Class.cancel(event)
n100+.. method:: scheduler.cancel(event)
79
80   Remove the event from the queue. If *event* is not an event currently in the
81   queue, this method will raise a :exc:`RuntimeError`.
82
83
n84-.. method:: XXX Class.empty()
n106+.. method:: scheduler.empty()
85
86   Return true if the event queue is empty.
87
88
n89-.. method:: XXX Class.run()
n111+.. method:: scheduler.run()
90
91   Run all scheduled events. This function will wait  (using the :func:`delayfunc`
92   function passed to the constructor) for the next event, then execute it and so
93   on until there are no more scheduled events.
94
95   Either *action* or *delayfunc* can raise an exception.  In either case, the
96   scheduler will maintain a consistent state and propagate the exception.  If an
97   exception is raised by *action*, the event will not be attempted in future calls
98   to :meth:`run`.
99
100   If a sequence of events takes longer to run than the time available before the
101   next event, the scheduler will simply fall behind.  No events will be dropped;
102   the calling code is responsible for canceling  events which are no longer
103   pertinent.
104
t127+.. attribute:: scheduler.queue
128+ 
129+   Read-only attribute returning a list of upcoming events in the order they
130+   will be run.  Each event is shown as a :term:`named tuple` with the
131+   following fields:  time, priority, action, argument.
132+ 
133+   .. versionadded:: 2.6
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op