PageRenderTime 72ms CodeModel.GetById 40ms app.highlight 4ms RepoModel.GetById 16ms app.codeStats 0ms

/Doc/library/sched.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 133 lines | 96 code | 37 blank | 0 comment | 0 complexity | 415ed955347665198888734957895796 MD5 | raw file
  1:mod:`sched` --- Event scheduler
  2================================
  3
  4.. module:: sched
  5   :synopsis: General purpose event scheduler.
  6.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
  7
  8.. index:: single: event scheduling
  9
 10The :mod:`sched` module defines a class which implements a general purpose event
 11scheduler:
 12
 13
 14.. class:: scheduler(timefunc, delayfunc)
 15
 16   The :class:`scheduler` class defines a generic interface to scheduling events.
 17   It needs two functions to actually deal with the "outside world" --- *timefunc*
 18   should be callable without arguments, and return  a number (the "time", in any
 19   units whatsoever).  The *delayfunc* function should be callable with one
 20   argument, compatible with the output of *timefunc*, and should delay that many
 21   time units. *delayfunc* will also be called with the argument ``0`` after each
 22   event is run to allow other threads an opportunity to run in multi-threaded
 23   applications.
 24
 25Example::
 26
 27   >>> import sched, time
 28   >>> s = sched.scheduler(time.time, time.sleep)
 29   >>> def print_time(): print "From print_time", time.time()
 30   ...
 31   >>> def print_some_times():
 32   ...     print time.time()
 33   ...     s.enter(5, 1, print_time, ())
 34   ...     s.enter(10, 1, print_time, ())
 35   ...     s.run()
 36   ...     print time.time()
 37   ...
 38   >>> print_some_times()
 39   930343690.257
 40   From print_time 930343695.274
 41   From print_time 930343700.273
 42   930343700.276
 43
 44In multi-threaded environments, the :class:`scheduler` class has limitations
 45with respect to thread-safety, inability to insert a new task before
 46the one currently pending in a running scheduler, and holding up the main
 47thread until the event queue is empty.  Instead, the preferred approach
 48is to use the :class:`threading.Timer` class instead.
 49
 50Example::
 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
 70
 71.. _scheduler-objects:
 72
 73Scheduler Objects
 74-----------------
 75
 76:class:`scheduler` instances have the following methods and attributes:
 77
 78
 79.. method:: scheduler.enterabs(time, priority, action, argument)
 80
 81   Schedule a new event. The *time* argument should be a numeric type compatible
 82   with the return value of the *timefunc* function passed  to the constructor.
 83   Events scheduled for the same *time* will be executed in the order of their
 84   *priority*.
 85
 86   Executing the event means executing ``action(*argument)``.  *argument* must be a
 87   sequence holding the parameters for *action*.
 88
 89   Return value is an event which may be used for later cancellation of the event
 90   (see :meth:`cancel`).
 91
 92
 93.. method:: scheduler.enter(delay, priority, action, argument)
 94
 95   Schedule an event for *delay* more time units. Other then the relative time, the
 96   other arguments, the effect and the return value are the same as those for
 97   :meth:`enterabs`.
 98
 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()
112
113   Run all scheduled events. This function 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   Either *action* or *delayfunc* can raise an exception.  In either case, the
118   scheduler will maintain a consistent state and propagate the exception.  If an
119   exception is raised by *action*, the event will not be attempted in future calls
120   to :meth:`run`.
121
122   If a sequence of events takes longer to run than the time available before the
123   next event, the scheduler will simply fall behind.  No events will be dropped;
124   the calling code is responsible for canceling  events which are no longer
125   pertinent.
126
127.. 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