Add a new alias for channels `async close()` called `aclose()`

[llucax]

In Python there are already a few async close methods, like for async generators. It also includes a aclosing context manager to automatically close these objects.

Also mark close() as deprecated.

[llucax]

@shsms on #408 (comment):

Wait, haven't we spoken about this many times already? The close method doesn't wait for the channel to drain completely and fully close. It just stops the channel from accepting new messages, and initiates the close process, and so aclose doesn't make sense?

Maybe we change the implementation to wait until the receivers are drained? Alternatively, create a task that would trigger the condition variable, and make close sync.

Yeah, but I'm not sure we got it right. I think we can still make the distinction between (a)close and stop as (a)close only starts the cleaning up process (I would say is more analogous to cancel) and stop guarantees that all cleanup is one when it returns. So aclose() is semantically equivalent to close(), but needs to call some other async code to initiate the cleanup.

I tried to look into similar cases in Python, and I can't find a clear pattern. For one side there is aclosing(), but I could only found 2 objects providing a aclose(): AsyncExitStack and AsyncGenerator. In their docs it is not clear to me if they don't await until the cleanup is done, but AsyncExitStack says that is the equivalent of ExitStack.close(), but it can call async cleanup functions too (so it matches the definition of semantically the same as close() but needing to use async code to do that), and AsyncGenerator is described in the Expressions section of the reference:

If an asynchronous generator happens to exit early by break, the caller task being cancelled, or other exceptions, the generator’s async cleanup code will run and possibly raise exceptions or access context variables in an unexpected context–perhaps after the lifetime of tasks it depends, or during the event loop shutdown when the async-generator garbage collection hook is called. To prevent this, the caller must explicitly close the async generator by calling aclose() method to finalize the generator and ultimately detach it from the event loop.

So it also looks a bit like it is just cleaning up stuff but not necessarily waiting until any pending processing is done.

Another similar case is with asyncio streams, but in that case they decided to keep close() as sync, and add a separate wait_closed().

import asyncio

async def tcp_echo_client(message):
    reader, writer = await asyncio.open_connection(
        '127.0.0.1', 8888)

    print(f'Send: {message!r}')
    writer.write(message.encode())
    await writer.drain()

    data = await reader.read(100)
    print(f'Received: {data.decode()!r}')

    print('Close the connection')
    writer.close()
    await writer.wait_closed()

asyncio.run(tcp_echo_client('Hello World!'))

But in this case you can actually have a sync close() (you just make a buffered send that doesn't need to await for anything).

[llucax]

Conclusion, for me aclose() as "same as close() but needs to call async code to start the cleanup" makes enough sense. For 2.0 we could see if we want to keep this or revisit it, but renaming close() to aclose() fixes our current issue in a pretty simple backwards-compatible way.

[shsms]

Quoting from: https://peps.python.org/pep-0525/

Implement an aclose method on asynchronous generators returning a special awaitable. When awaited it throws a GeneratorExit into the suspended generator and iterates over it until either a GeneratorExit or a StopAsyncIteration occur.

This means that the aclose method will not return until the iterator is closed completely.

And the description here seems to suggest the same: https://docs.python.org/3/reference/expressions.html#agen.aclose

If the asynchronous generator yields a value, a RuntimeError is raised by the awaitable.

It is much more expressive and lets the user know that the close didn't happen, which is very different from the behaviour of close.

If we also implement that behaviour of waiting for receivers to drain fully, I wouldn't mind going this route.

That said, we do block sending as soon as this is called, and we can think of the receivers as external objects that are not affected by the channels. So I think I'm okay with going this route.