Add advice on choosing between scheduler and threading.Timer().
diff --git a/Doc/library/sched.rst b/Doc/library/sched.rst
index 1007cfb..e9619fb 100644
--- a/Doc/library/sched.rst
+++ b/Doc/library/sched.rst
@@ -41,6 +41,31 @@
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, 1, print_time, ())
+ ... print time.time() # executes before the time-delay events
+ ...
+ >>> print_some_times()
+ 930343690.257
+ 930343690.301
+ From print_time 930343695.274
+ From print_time 930343700.273
+
.. _scheduler-objects: