|
| 1 | +% LaTeXed and enhanced from comments in file |
| 2 | +\section{\module{sched} --- |
| 3 | + Event scheduler} |
| 4 | + |
| 5 | +\declaremodule{standard}{sched} |
| 6 | +\sectionauthor{Moshe Zadka}{ [email protected]} |
| 7 | +\modulesynopsis{General purpose event scheduler.} |
| 8 | + |
| 9 | +The \module{sched} module defines a class which implements a general |
| 10 | +purpose event scheduler: |
| 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{Schedule Objects \label{schedule-objects}} |
| 47 | + |
| 48 | +\class{schdule} 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 | +Check whether there are no scheduled events. |
| 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} |
0 commit comments