| % LaTeXed and enhanced from comments in file |
| \section{\module{sched} --- |
| Event scheduler} |
| |
| \declaremodule{standard}{sched} |
| \sectionauthor{Moshe Zadka}{mzadka@geocities.com} |
| \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 to the return value of \var{timefunc}. Events scheduled for |
| the same \var{time} will be executed in the order of their |
| \var{priority}. |
| |
| Executing the event means executing \code{apply(\var{action}, |
| \var{argument})}. \var{argument} must be a tuple 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 cancelling |
| events which are no longer pertinent. |
| \end{methoddesc} |