ref: 5513dae7d9eee46f7e1843c8eeeaf9066d0ec632
dir: /sys/src/cmd/python/Doc/lib/libsched.tex/
\section{\module{sched} ---
Event scheduler}
% LaTeXed and enhanced from comments in file
\declaremodule{standard}{sched}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
\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}