Moshe's section on the sched module, with edits.

1 files changed, 95 insertions, 0 deletions

diff --git a/Doc/lib/libsched.tex b/Doc/lib/libsched.tex
new file mode 100644
index 0000000..afa9c6f
--- /dev/null
+++ b/Doc/lib/libsched.tex
@@ -0,0 +1,95 @@
+% 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:
+
+\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{Schedule Objects \label{schedule-objects}}
+
+\class{schdule} 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}{}
+Check whether there are no scheduled events.
+\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}