source: trunk/essentials/dev-lang/python/Doc/lib/libsched.tex@ 3368

\section{\module{sched} ---
         Event scheduler}

% LaTeXed and enhanced from comments in file

\declaremodule{standard}{sched}
\sectionauthor{Moshe Zadka}{[email protected]}
\modulesynopsis{General purpose event scheduler.}

The \module{sched} module defines a class which implements a general
purpose event scheduler:\index{event scheduling}

\begin{classdesc}{scheduler}{timefunc, delayfunc}
The \class{scheduler} class defines a generic interface to scheduling
events. It needs two functions to actually deal with the ``outside world''
--- \var{timefunc} should be callable without arguments, and return 
a number (the ``time'', in any units whatsoever).  The \var{delayfunc}
function should be callable with one argument, compatible with the output
of \var{timefunc}, and should delay that many time units.
\var{delayfunc} will also be called with the argument \code{0} after
each event is run to allow other threads an opportunity to run in
multi-threaded applications.
\end{classdesc}

Example:

\begin{verbatim}
>>> import sched, time
>>> s=sched.scheduler(time.time, time.sleep)
>>> def print_time(): print "From print_time", time.time()
...
>>> def print_some_times():
...     print time.time()
...     s.enter(5, 1, print_time, ())
...     s.enter(10, 1, print_time, ())
...     s.run()
...     print time.time()
...
>>> print_some_times()
930343690.257
From print_time 930343695.274
From print_time 930343700.273
930343700.276
\end{verbatim}


\subsection{Scheduler Objects \label{scheduler-objects}}

\class{scheduler} instances have the following methods:

\begin{methoddesc}{enterabs}{time, priority, action, argument}
Schedule a new event. The \var{time} argument should be a numeric type
compatible with the return value of the \var{timefunc} function passed 
to the constructor. Events scheduled for
the same \var{time} will be executed in the order of their
\var{priority}.

Executing the event means executing
\code{\var{action}(*\var{argument})}.  \var{argument} must be a
sequence holding the parameters for \var{action}.

Return value is an event which may be used for later cancellation of
the event (see \method{cancel()}).
\end{methoddesc}

\begin{methoddesc}{enter}{delay, priority, action, argument}
Schedule an event for \var{delay} more time units. Other then the
relative time, the other arguments, the effect and the return value
are the same as those for \method{enterabs()}.
\end{methoddesc}

\begin{methoddesc}{cancel}{event}
Remove the event from the queue. If \var{event} is not an event
currently in the queue, this method will raise a
\exception{RuntimeError}.
\end{methoddesc}

\begin{methoddesc}{empty}{}
Return true if the event queue is empty.
\end{methoddesc}

\begin{methoddesc}{run}{}
Run all scheduled events. This function will wait 
(using the \function{delayfunc} function passed to the constructor)
for the next event, then execute it and so on until there are no more
scheduled events.

Either \var{action} or \var{delayfunc} can raise an exception.  In
either case, the scheduler will maintain a consistent state and
propagate the exception.  If an exception is raised by \var{action},
the event will not be attempted in future calls to \method{run()}.

If a sequence of events takes longer to run than the time available
before the next event, the scheduler will simply fall behind.  No
events will be dropped; the calling code is responsible for canceling 
events which are no longer pertinent.
\end{methoddesc}