https://bugs.python.org/issue41756 has introduced PyIter_Send as a common entrypoint for sending values however currently fast path that does not use StopIteration exception is only available for generators/coroutines. It would be quite nice if this machinery was extensible and other types (both internal and 3rd party) could opt-in into using exception-free way of returning values without needing to update the implementation of PyIter_Send. One way of solving this is adding a new slot with a signature that matches PyIter_Send. With it:
- it should be possible to implement this slot for coroutines/generators and remove  special casing for them  in PyIter_Send
- provide implementation for this slot for internal types (i.e. FutureIter in _asynciomodule.c) - results of this experiment can be found below
- enable external native extensions to provide efficient implementation of coroutines (i.e.  Cython could benefit from it)

Microbenchmark to demonstrate the difference of accessing the value of fulfiled Future without and with dedicated slot:
```
import asyncio
import time

N = 100000000

async def run():
    fut = asyncio.Future()
    fut.set_result(42)

    t0 = time.time()
    for _ in range(N):
        await fut
    t1 = time.time()
    print(f"Time: {t1 - t0} s")

asyncio.run(run())
```
Time: 8.365560054779053 s - without the slot
Time: 5.799655914306641 s - with the  slot

New changeset 1e996c3a3b51e9c6f1f4cea8a6dbcf3bcb865060 by Vladimir Matveev in branch 'master':
bpo-42085: Introduce dedicated entry in PyAsyncMethods for sending values (#22780)
https://github.com/python/cpython/commit/1e996c3a3b51e9c6f1f4cea8a6dbcf3bcb865060

Vladimir, please do a follow up PR documenting Py_TPFLAGS_HAVE_AM_SEND.

> New changeset 1e996c3a3b51e9c6f1f4cea8a6dbcf3bcb865060 by Vladimir Matveev in branch 'master':

This change introduced big reference leaks:

4 tests failed:
    test_asyncgen test_asyncio test_coroutines test_unittest

Example:

$ ./python -m test test_asyncgen -R 3:3 -m test.test_asyncgen.AsyncGenAsyncioTest.test_async_gen_asyncio_03
(...)
test_asyncgen leaked [63, 63, 63] references, sum=189
(...)

Please fix the leak, or revert if nobody is avaible to fix it:
https://pythondev.readthedocs.io/ci.html#revert-on-fail

Investigating. The test leaks a future instance.

PR for the fix is created: https://github.com/python/cpython/pull/23237

commit cda99b4022daa08ac74b0420e9903cce883d91c6 (HEAD -> master, upstream/master)
Author: Andrew Svetlov <andrew.svetlov@gmail.com>
Date:   Wed Nov 11 17:48:53 2020 +0200

    Fix memory leak introduced by GH-22780 (GH-23237)

Thanks! The change fixed the leak:

$ ./python -m test -j0 -R 3:3 test_asyncgen test_coroutines test_unittest # test_asyncio 
(...)
Tests result: SUCCESS

I didn't run test_asyncio because the test is too slow.

Thank you Victor for the report!

New changeset 7c9487ded487f304c2906698c52f0815b92cbeb6 by Vladimir Matveev in branch 'master':
bpo-42085: Add documentation for Py_TPFLAGS_HAVE_AM_SEND (GH-23374)
https://github.com/python/cpython/commit/7c9487ded487f304c2906698c52f0815b92cbeb6

Is anything left to do?

> Is anything left to do?

I think we can close this now.

New changeset 0b11c429c7f1721d9ffb9ae19e3e8e2e7bd6444d by Martmists in branch 'main':
bpo-42085: [docs] Add versionadded for am_send in type object documentation (GH-25465)
https://github.com/python/cpython/commit/0b11c429c7f1721d9ffb9ae19e3e8e2e7bd6444d

New changeset d338ce0796e5fe8e54dfe52f93ed9d5936ad3efe by Miss Islington (bot) in branch '3.10':
bpo-42085: [docs] Add versionadded for am_send in type object documentation (GH-25465) (GH-26453)
https://github.com/python/cpython/commit/d338ce0796e5fe8e54dfe52f93ed9d5936ad3efe

Py_TPFLAGS_HAVE_AM_SEND is unnecessary and I'd like to remove it.

It is not possible for type objects to have a different layout than the interpreter:
- extensions using the regular ABI must be recompiled for each feature version of Python
- extensions using the stable ABI can only create types dynamically

Or is there a different reason for Py_TPFLAGS_HAVE_AM_SEND? Checking it may be faster than ((Py_TYPE(x)->tp_as_async != NULL) && (Py_TYPE(x)->tp_as_async->am_send != NULL)), but I don't think the speedup is relevant.

See bpo-42747

Is there documentation anywhere for the semantics of am_send? I only see the signature followed by "See PyIter_Send for details", but the doc for PyIter_Send doesn't mention am_send.

In particular, it would be nice to document the relationship between PyIter_Send, am_send, and tp_iternext.

I am reopening this issue since am_send never got documented here: https://docs.python.org/3/c-api/typeobj.html#async-structs

It did get added to the correct docs:

https://docs.python.org/3.10/c-api/typeobj.html#c.PyAsyncMethods.am_send

(the 3.10 and 3.11 docs, not the 3.9 docs ;-)

But as I mentioned, I feel that there could be more details about the semantics/contract.

Oh, my bad. I can't find the enum values of the return type, though (PySendResult).