Corrected documentation and logging semantics of scheduler startup and shutdown; made shutdown() always wait for the scheduler thread to exit

4 files changed, 28 insertions, 31 deletions

diff --git a/apscheduler/scheduler.py b/apscheduler/scheduler.py
index b51487a..8534e3f 100644
--- a/apscheduler/scheduler.py
+++ b/apscheduler/scheduler.py
@@ -103,30 +103,27 @@ class Scheduler(object):
         self._thread.setDaemon(self.daemonic)
         self._thread.start()
 
-        # Notify listeners that the scheduler has been started
-        self._notify_listeners(SchedulerEvent(EVENT_SCHEDULER_START))
-
-        logger.info('Scheduler started')
-
-    def shutdown(self, timeout=0):
+    def shutdown(self, wait=True, shutdown_threadpool=True):
         """
         Shuts down the scheduler and terminates the thread.
-        Does not terminate any currently running jobs.
+        Does not interrupt any currently running jobs.
 
-        :param timeout: time (in seconds) to wait for the scheduler thread to
-            terminate, ``0`` to wait forever, ``None`` to skip waiting
+        :param wait: ``True`` to wait until all currently executing jobs have
+                     finished (if ``shutdown_threadpool`` is also ``True``)
+        :param shutdown_threadpool: ``True`` to shut down the thread pool
         """
         if not self.running:
             return
 
-        logger.info('Scheduler shutting down')
         self._stopped = True
         self._wakeup.set()
-        if timeout is not None:
-            self._thread.join(timeout)
 
-        # Notify listeners that the scheduler has been shut down
-        self._notify_listeners(SchedulerEvent(EVENT_SCHEDULER_SHUTDOWN))
+        # Shut down the thread pool
+        if shutdown_threadpool:
+            self._threadpool.shutdown(wait)
+
+        # Wait until the scheduler thread terminates
+        self._thread.join()
 
     @property
     def running(self):
@@ -507,6 +504,7 @@ class Scheduler(object):
     def _main_loop(self):
         """Executes jobs on schedule."""
 
+        logger.info('Scheduler started')
         self._notify_listeners(SchedulerEvent(EVENT_SCHEDULER_START))
 
         self._wakeup.clear()
@@ -527,4 +525,5 @@ class Scheduler(object):
                 self._wakeup.wait()
             self._wakeup.clear()
 
+        logger.info('Scheduler has been shut down')
         self._notify_listeners(SchedulerEvent(EVENT_SCHEDULER_SHUTDOWN))
diff --git a/docs/index.rst b/docs/index.rst
index 07e26a0..7085ba0 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -123,28 +123,24 @@ run retroactively in such cases.
 Shutting down the scheduler
 ---------------------------
 
-::
+To shut down the scheduler::
 
     sched.shutdown()
 
-A scheduler that has been shut down can be restarted, but the shutdown
-procedure clears any scheduled non-persistent jobs.
+By default, the scheduler shuts down its thread pool and waits until all
+currently executing jobs are finished. For a faster exit you can do::
 
-If you want to make sure that the scheduler has really terminated, you
-can specify a timeout (in seconds)::
+    sched.shutdown(wait=False)
 
-    sched.shutdown(10)
+This will still shut down the thread pool but does not wait for any running
+tasks to complete. Also, if you gave the scheduler a thread pool that you want
+to manage elsewhere, you probably want to skip the thread pool shutdown
+altogether::
 
-This will wait at most 10 seconds for the scheduler thread to terminate,
-and then proceed anyways.
+    sched.shutdown(shutdown_threadpool=False)
 
-To make sure that the scheduler has terminated, you can specify
-a timeout of 0. This will disable the waiting timeout and will wait as long as
-it takes for the scheduler to shut down.
-
-.. note::
-	Shutting down the scheduler does not guarantee that all jobs have
-	terminated.
+This implies ``wait=False``, since there is no way to wait for the scheduler's
+tasks to finish without shutting down the thread pool.
 
 
 Scheduler configuration options
diff --git a/docs/migration.rst b/docs/migration.rst
index ccdb214..f6b13f6 100644
--- a/docs/migration.rst
+++ b/docs/migration.rst
@@ -20,6 +20,8 @@ API changes
   universal ``max_runs`` option
 * :meth:`~apscheduler.scheduler.Scheduler.unschedule_func` now raises a
   KeyError if the given function is not scheduled
+* The semantics of :meth:`~apscheduler.scheduler.Scheduler.shutdown`` have
+  changed -- the method no longer accepts a numeric argument, but two booleans;
 
 
 Configuration changes
diff --git a/tests/testscheduler.py b/tests/testscheduler.py
index 9ac75a5..7b2a566 100644
--- a/tests/testscheduler.py
+++ b/tests/testscheduler.py
@@ -383,7 +383,7 @@ class TestRunningScheduler(object):
             self.scheduler.shutdown()
 
     def test_shutdown_timeout(self):
-        self.scheduler.shutdown(3)
+        self.scheduler.shutdown()
 
     @raises(SchedulerAlreadyRunningError)
     def test_scheduler_double_start(self):
@@ -394,5 +394,5 @@ class TestRunningScheduler(object):
         self.scheduler.configure({})
 
     def test_scheduler_double_shutdown(self):
-        self.scheduler.shutdown(1)
         self.scheduler.shutdown()
+        self.scheduler.shutdown(False)