From c92695253a65420cfe352efb9e094e82b8a5bf26 Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Mon, 5 Sep 2016 21:35:57 +0800 Subject: [PATCH] docs: Document some subtleties of native coroutines --- docs/guide/coroutines.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/guide/coroutines.rst b/docs/guide/coroutines.rst index 2fefcb4b9..2bac028fd 100644 --- a/docs/guide/coroutines.rst +++ b/docs/guide/coroutines.rst @@ -143,7 +143,11 @@ the `.IOLoop` will log a stack trace:: # we pass the function object to be called by the IOLoop. IOLoop.current().spawn_callback(divide, 1, 0) -Finally, at the top level of a program, *if the `.IOLoop` is not yet +Using `.IOLoop.spawn_callback` in this way is *recommended* for +functions using ``@gen.coroutine``, but it is *required* for functions +using ``async def`` (otherwise the coroutine runner will not start). + +Finally, at the top level of a program, *if the IOLoop is not yet running,* you can start the `.IOLoop`, run the coroutine, and then stop the `.IOLoop` with the `.IOLoop.run_sync` method. This is often used to start the ``main`` function of a batch-oriented program:: @@ -235,6 +239,12 @@ immediately, so you can start another operation before waiting: .. testoutput:: :hide: +This pattern is most usable with ``@gen.coroutine``. If +``fetch_next_chunk()`` uses ``async def``, then it must be called as +``fetch_future = +tornado.gen.convert_yielded(self.fetch_next_chunk())`` to start the +background processing. + Looping ^^^^^^^ -- 2.47.2