Doc/lib/libsched.tex

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