classification
Title: Add documentation for METH_FASTCALL and _PyObject_FastCall*()
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, docs@python, haypo, serhiy.storchaka, skrah
Priority: normal Keywords:

Created on 2016-11-26 11:08 by skrah, last changed 2017-10-04 15:19 by haypo.

Messages (9)
msg281766 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-11-26 11:08
It looks like METH_FASTCALL gives nice speedups (#28754).

Is this an internal interface or can it be documented like
METH_KEYWORDS etc.?
msg281771 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-11-26 11:59
I suggest to keep it internal. It's meaning may be changed in future. I have some ideas about making it more convenient and faster (but I'm not sure that they would work).
msg281778 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2016-11-26 15:06
Is it possible to use Argument Clinic for third party extensions? If yes, I
suggest to use it.

It would also be nice if Cython could use it automatically. So we can
suggest to use Cython. I don't know well Cython, maybe your idea is very
dumb :-)

Serhiy Storchaka added the comment:
> I suggest to keep it internal. It's meaning may be changed in future. I
have some ideas about making it more convenient and faster (but I'm not
sure that they would work).

Ah? Can you please elaborate your secret plan? :-)
msg281784 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2016-11-26 17:32
There are a couple of problems with using Argument Clinic for third
party projects.

First, it makes no stability promises:

"Currently Argument Clinic is considered internal-only for CPython. ..."


Then, for large projects that already use some generated code (like
NumPy), IMO the result would be unmaintainable.


So it would be nice to have a public stable API -- of course there
is no hurry if Serhiy has plans to improve it.
msg281785 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-11-26 17:43
> Ah? Can you please elaborate your secret plan? :-)

I already said about this. Move the part of parsing keyword argument outside of the function. The caller should unpack keyword arguments and pass just a raw array of PyObject*. Missed arguments are set to NULL. This could make _PyArg_ParseStack() simpler and might even allow to inline arguments parsing code.
msg303701 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2017-10-04 15:13
This and the _PyObject_FastCall* APIs really do need to be documented, especially if they're going to be used in the interpreter itself.  The leading underscore signifies that it's not part of the public API (well, METH_FASTCALL doesn't have a leading underscore).

When these are not documented, then they aren't discoverable, so there are cases where it may be useful but will be overlooked.  It also means that folks will be inclined to cargo cult the few existing uses without perhaps understanding the full semantics.

Can we please document these for Python 3.7 at least?
msg303702 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-10-04 15:16
> Can we please document these for Python 3.7 at least?

I chose to not document FASTCALL on purpose in Python 3.6, I wanted to keep everything private, until we get enough feedback and stabilize the API.

Recently, the FASTCALL API changed: METH_FASTCALL doesn't support keywords anymore. You have to pass METH_FASTCALL|METH_KEYWORDS.

It seems like the API became stable.

I don't know if we should make the API public or not. PyPy would complain as usual that we give them more work to do :-D
msg303703 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-10-04 15:18
I suggest to document the following 4 functions/macros:

PyAPI_FUNC(PyObject *) _PyObject_FastCallDict(
    PyObject *callable,
    PyObject **args,
    Py_ssize_t nargs,
    PyObject *kwargs);

PyAPI_FUNC(PyObject *) _PyObject_FastCallKeywords(
    PyObject *callable,
    PyObject **args,
    Py_ssize_t nargs,
    PyObject *kwnames);

#define _PyObject_FastCall(func, args, nargs) \
    _PyObject_FastCallDict((func), (args), (nargs), NULL)

#define _PyObject_CallNoArg(func) \
    _PyObject_FastCallDict((func), NULL, 0, NULL)

And the METH_FASTCALL and METH_FASTCALL|METH_KEYWORDS calling convention.
msg303704 - (view) Author: STINNER Victor (haypo) * (Python committer) Date: 2017-10-04 15:19
> It would also be nice if Cython could use it automatically.

Cython is using FASTCALL since Python 3.6.
History
Date User Action Args
2017-10-04 15:19:37hayposetmessages: + msg303704
2017-10-04 15:18:55hayposetmessages: + msg303703
2017-10-04 15:16:57hayposetmessages: + msg303702
2017-10-04 15:13:32barrysettitle: Add documentation for METH_FASTCALL -> Add documentation for METH_FASTCALL and _PyObject_FastCall*()
2017-10-04 15:13:16barrysetnosy: + barry

messages: + msg303701
versions: + Python 3.7
2016-11-26 17:43:53serhiy.storchakasetmessages: + msg281785
2016-11-26 17:32:49skrahsetmessages: + msg281784
2016-11-26 15:06:44hayposetmessages: + msg281778
2016-11-26 11:59:42serhiy.storchakasetmessages: + msg281771
2016-11-26 11:08:54skrahcreate