Clarify async documentation

[dhirschfeld]

I'm just testing out the distributed async support and seem to have hit a bug:

from tornado.ioloop import IOLoop
from dask.distributed import Client


client = Client()

async def f():
    print('A')
    future = client.submit(lambda x: x + 1, 10)
    print('B')
    result = await client.gather(future, asynchronous=True)
    print('C')
    return result

res = IOLoop().run_sync(f)
print(res)
client.close()

results in:

A
B
<HANG FOREVER>

I'm on win64 running:

python      3.6.5
distributed 1.22.0+9.gdb758d0f
dask        0.18.0

[dhirschfeld]

Interesting data point:

async def f():
    print('A')
    future = client.submit(lambda x: x + 1, 10)
    print('B')
    result = await future
    print('C')
    return result

results in:

A
B
Traceback (most recent call last):
  File "C:/Users/dhirschf/.PyCharm2018.1/config/scratches/scratch_30.py", line 16, in <module>
    res = IOLoop().run_sync(f)
  File "C:\Miniconda3\lib\site-packages\tornado\ioloop.py", line 581, in run_sync
    return future_cell[0].result()
  File "C:/Users/dhirschf/.PyCharm2018.1/config/scratches/scratch_30.py", line 12, in f
    result = await future
  File "C:\Miniconda3\lib\site-packages\distributed\client.py", line 364, in __await__
    return self.result().__await__()
AttributeError: 'int' object has no attribute '__await__'

[dhirschfeld]

In the original example if I step into the asyncio.events code in the PyCharm debugger it works correctly:

A
B
C
11

[dhirschfeld]

What does work is creating an async-client inside the function itself:

async def f():
	"""This works!"""
    with Client(asynchronous=True) as client:
        future = client.submit(lambda x: x + 1, 10)
        result = await client.gather(future)
    return result

Creating a normal client inside the function and passing the asynchronous=True argument to gather also hangs at the gather

async def f():
	"""This hangs at the gather"""
    with Client() as client:
        future = client.submit(lambda x: x + 1, 10)
        result = await client.gather(future, asynchronous=True)
    return result

[mrocklin]

When you create a client like Client() it creates a running IOLoop for you in a separate thread, available as client.loop. You need to use that loop for any async operation.

I recommend using client.sync(f) if you want to run an async function (also, use master if you're using async def rather than @gen.coroutine with client.sync

[dhirschfeld]

Thanks for the help @mrocklin! I'm still a little unclear on the solution though...

You need to use that loop for any async operation

I'm not quite sure how to do that since AFAICS gather doesn't take a loop argument? Are the docs linked below incorrect?

distributed/docs/source/asynchronous.rst

Lines 47 to 59 in 94f076c

	If you want to reuse the same client in asynchronous and synchronous
	environments you can apply the ``asynchronous=True`` keyword at each method
	call.
	.. code-block:: python
	client = Client() # normal blocking client
	async def f():
	futures = client.map(func, L)
	results = await client.gather(futures, asynchronous=True)
	return results

I recommend using client.sync(f) if you want to run an async function

I got the implementation from the docs, but I see it might be a different usecase - the client is constructed in the function itself so there isn't one externally to run the function?

distributed/docs/source/asynchronous.rst

Lines 93 to 109 in 94f076c

	Python 3 with Tornado
	+++++++++++++++++++++
	.. code-block:: python
	from dask.distributed import Client
	async def f():
	client = await Client(asynchronous=True)
	future = client.submit(lambda x: x + 1, 10)
	result = await future
	await client.close()
	return result
	from tornado.ioloop import IOLoop
	IOLoop().run_sync(f)

[mrocklin]

Gather will always use the client's IOLoop. This is why, when you call it from another IOLoop, nothing happens.

res = IOLoop().run_sync(f)   # This is bad

If you need to specify an IOLoop then you pass the IOLoop to the Client constructor, not to the function.

but I see it might be a different usecase - the client is constructed in the function itself so there isn't one externally to run the function?

If you are constructing a client within an asynchronous function then you should pass asynchronous=True. It will use the current IOLoop by default.

[dhirschfeld]

Thanks for the clarification - I think I get it now! I've changed the name of the issue and I'll see if I can put in a PR to the docs to include some of this info...

[mrocklin]

Any update on this @dhirschfeld ?

[dhirschfeld]

I do intend to submit a very small patch for review - just a matter of finding the time to do it! As far as timelines go; hopefully i'll find time this month...