Doc/library/sched.rst

   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
  10 The :mod:`sched` module defines a class which implements a general purpose event
  11 scheduler:
  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
  25 Example::
  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
  44 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
  70
  71 .. _scheduler-objects:
  72
  73 Scheduler 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