--- rest25/library/sched.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/sched.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,104 +1,133 @@
-
 :mod:`sched` --- Event scheduler
 ================================
 
 .. module:: sched
    :synopsis: General purpose event scheduler.
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
-
-.. % LaTeXed and enhanced from comments in file
-
 .. index:: single: event scheduling
 
 The :mod:`sched` module defines a class which implements a general purpose event
 scheduler:
 
 
 .. class:: 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" --- *timefunc*
    should be callable without arguments, and return  a number (the "time", in any
    units whatsoever).  The *delayfunc* function should be callable with one
    argument, compatible with the output of *timefunc*, and should delay that many
    time units. *delayfunc* will also be called with the argument ``0`` after each
    event is run to allow other threads an opportunity to run in multi-threaded
    applications.
 
 Example::
 
    >>> import sched, time
-   >>> s=sched.scheduler(time.time, time.sleep)
+   >>> 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
 
+In multi-threaded environments, the :class:`scheduler` class has limitations
+with respect to thread-safety, inability to insert a new task before
+the one currently pending in a running scheduler, and holding up the main
+thread until the event queue is empty.  Instead, the preferred approach
+is to use the :class:`threading.Timer` class instead.
+
+Example::
+
+    >>> import time
+    >>> from threading import Timer
+    >>> def print_time():
+    ...     print "From print_time", time.time()
+    ...
+    >>> def print_some_times():
+    ...     print time.time()
+    ...     Timer(5, print_time, ()).start()
+    ...     Timer(10, print_time, ()).start()
+    ...     time.sleep(11)  # sleep while time-delay events execute
+    ...     print time.time()
+    ...
+    >>> print_some_times()
+    930343690.257
+    From print_time 930343695.274
+    From print_time 930343700.273
+    930343701.301
+
 
 .. _scheduler-objects:
 
 Scheduler Objects
 -----------------
 
-:class:`scheduler` instances have the following methods:
+:class:`scheduler` instances have the following methods and attributes:
 
 
-.. method:: XXX Class.enterabs(time, priority, action, argument)
+.. method:: scheduler.enterabs(time, priority, action, argument)
 
    Schedule a new event. The *time* argument should be a numeric type compatible
    with the return value of the *timefunc* function passed  to the constructor.
    Events scheduled for the same *time* will be executed in the order of their
    *priority*.
 
    Executing the event means executing ``action(*argument)``.  *argument* must be a
    sequence holding the parameters for *action*.
 
    Return value is an event which may be used for later cancellation of the event
    (see :meth:`cancel`).
 
 
-.. method:: XXX Class.enter(delay, priority, action, argument)
+.. method:: scheduler.enter(delay, priority, action, argument)
 
    Schedule an event for *delay* more time units. Other then the relative time, the
    other arguments, the effect and the return value are the same as those for
    :meth:`enterabs`.
 
 
-.. method:: XXX Class.cancel(event)
+.. method:: scheduler.cancel(event)
 
    Remove the event from the queue. If *event* is not an event currently in the
    queue, this method will raise a :exc:`RuntimeError`.
 
 
-.. method:: XXX Class.empty()
+.. method:: scheduler.empty()
 
    Return true if the event queue is empty.
 
 
-.. method:: XXX Class.run()
+.. method:: scheduler.run()
 
    Run all scheduled events. This function will wait  (using the :func:`delayfunc`
    function passed to the constructor) for the next event, then execute it and so
    on until there are no more scheduled events.
 
    Either *action* or *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 *action*, the event will not be attempted in future calls
    to :meth:`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.
 
+.. attribute:: scheduler.queue
+
+   Read-only attribute returning a list of upcoming events in the order they
+   will be run.  Each event is shown as a :term:`named tuple` with the
+   following fields:  time, priority, action, argument.
+
+   .. versionadded:: 2.6
