mirror of https://github.com/python/cpython
98 lines
3.4 KiB
TeX
98 lines
3.4 KiB
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}
|