Doc/lib/libsched.tex

   1 \section{\module{sched} ---
   2          Event scheduler}
   3
   4 % LaTeXed and enhanced from comments in file
   5
   6 \declaremodule{standard}{sched}
   7 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   8 \modulesynopsis{General purpose event scheduler.}
   9
  10 The \module{sched} module defines a class which implements a general
  11 purpose event scheduler:\index{event scheduling}
  12
  13 \begin{classdesc}{scheduler}{timefunc, delayfunc}
  14 The \class{scheduler} class defines a generic interface to scheduling
  15 events. It needs two functions to actually deal with the ``outside world''
  16 --- \var{timefunc} should be callable without arguments, and return
  17 a number (the ``time'', in any units whatsoever).  The \var{delayfunc}
  18 function should be callable with one argument, compatible with the output
  19 of \var{timefunc}, and should delay that many time units.
  20 \var{delayfunc} will also be called with the argument \code{0} after
  21 each event is run to allow other threads an opportunity to run in
  22 multi-threaded applications.
  23 \end{classdesc}
  24
  25 Example:
  26
  27 \begin{verbatim}
  28 >>> import sched, time
  29 >>> s=sched.scheduler(time.time, time.sleep)
  30 >>> def print_time(): print "From print_time", time.time()
  31 ...
  32 >>> def print_some_times():
  33 ...     print time.time()
  34 ...     s.enter(5, 1, print_time, ())
  35 ...     s.enter(10, 1, print_time, ())
  36 ...     s.run()
  37 ...     print time.time()
  38 ...
  39 >>> print_some_times()
  40 930343690.257
  41 From print_time 930343695.274
  42 From print_time 930343700.273
  43 930343700.276
  44 \end{verbatim}
  45
  46
  47 \subsection{Scheduler Objects \label{scheduler-objects}}
  48
  49 \class{scheduler} instances have the following methods:
  50
  51 \begin{methoddesc}{enterabs}{time, priority, action, argument}
  52 Schedule a new event. The \var{time} argument should be a numeric type
  53 compatible with the return value of the \var{timefunc} function passed
  54 to the constructor. Events scheduled for
  55 the same \var{time} will be executed in the order of their
  56 \var{priority}.
  57
  58 Executing the event means executing \code{apply(\var{action},
  59 \var{argument})}.  \var{argument} must be a tuple holding the
  60 parameters for \var{action}.
  61
  62 Return value is an event which may be used for later cancellation of
  63 the event (see \method{cancel()}).
  64 \end{methoddesc}
  65
  66 \begin{methoddesc}{enter}{delay, priority, action, argument}
  67 Schedule an event for \var{delay} more time units. Other then the
  68 relative time, the other arguments, the effect and the return value
  69 are the same as those for \method{enterabs()}.
  70 \end{methoddesc}
  71
  72 \begin{methoddesc}{cancel}{event}
  73 Remove the event from the queue. If \var{event} is not an event
  74 currently in the queue, this method will raise a
  75 \exception{RuntimeError}.
  76 \end{methoddesc}
  77
  78 \begin{methoddesc}{empty}{}
  79 Return true if the event queue is empty.
  80 \end{methoddesc}
  81
  82 \begin{methoddesc}{run}{}
  83 Run all scheduled events. This function will wait
  84 (using the \function{delayfunc} function passed to the constructor)
  85 for the next event, then execute it and so on until there are no more
  86 scheduled events.
  87
  88 Either \var{action} or \var{delayfunc} can raise an exception.  In
  89 either case, the scheduler will maintain a consistent state and
  90 propagate the exception.  If an exception is raised by \var{action},
  91 the event will not be attempted in future calls to \method{run()}.
  92
  93 If a sequence of events takes longer to run than the time available
  94 before the next event, the scheduler will simply fall behind.  No
  95 events will be dropped; the calling code is responsible for canceling
  96 events which are no longer pertinent.
  97 \end{methoddesc}