ref: 1fe3143e4c43ce2c74e0cfdd70b1bd556bbb9e1b
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}{[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}