From: Ben Darnell Date: Sat, 24 Mar 2012 22:07:26 +0000 (-0700) Subject: Expand documentation for IOLoop.stop and IOLoop.close X-Git-Tag: v2.3.0~61 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2f0fbd9ba98440d0266f2e7726156a4a5cedb27c;p=thirdparty%2Ftornado.git Expand documentation for IOLoop.stop and IOLoop.close --- diff --git a/tornado/ioloop.py b/tornado/ioloop.py index ea1a9b500..abb2de02b 100644 --- a/tornado/ioloop.py +++ b/tornado/ioloop.py @@ -164,7 +164,20 @@ class IOLoop(object): """Closes the IOLoop, freeing any resources used. If ``all_fds`` is true, all file descriptors registered on the - IOLoop will be closed (not just the ones created by the IOLoop itself. + IOLoop will be closed (not just the ones created by the IOLoop itself). + + Many applications will only use a single IOLoop that runs for the + entire lifetime of the process. In that case closing the IOLoop + is not necessary since everything will be cleaned up when the + process exits. `IOLoop.close` is provided mainly for scenarios + such as unit tests, which create and destroy a large number of + IOLoops. + + An IOLoop must be completely stopped before it can be closed. This + means that `IOLoop.stop()` must be called *and* `IOLoop.start()` must + be allowed to return before attempting to call `IOLoop.close()`. + Therefore the call to `close` will usually appear just after + the call to `start` rather than near the call to `stop`. """ self.remove_handler(self._waker.fileno()) if all_fds: @@ -335,6 +348,9 @@ class IOLoop(object): ioloop.start() will return after async_method has run its callback, whether that callback was invoked before or after ioloop.start. + + Note that even after `stop` has been called, the IOLoop is not + completely stopped until `IOLoop.start` has also returned. """ self._running = False self._stopped = True