Most C API functions either succeed or fail. Those functions return NULL/not-NULL or 0/-1. No problem there.
However there are functions that can have three or more return kinds.
For example, found/not-found/error, yield/return/raise, or even less-than/equal/greater-than/unordered/error in the case of comparisons.
For those functions we want to return the kind as an int, setting any PyObject * results through an out pointer.
The devguide should document the preferred way to do this, to avoid endless debate for each new C API function.
See python/cpython#105201 (comment) for my preferred approach for three-way return values.
Four and five way return values other than for comparisons are sufficiently uncommon that they can be dealt with on an individual basis.
For comparisons, a slightly strange enum based on powers-of-two is to be used for efficient selection of the desired result by masking.
Most C API functions either succeed or fail. Those functions return
NULL/not-NULLor 0/-1. No problem there.However there are functions that can have three or more return kinds.
For example,
found/not-found/error,yield/return/raise, or evenless-than/equal/greater-than/unordered/errorin the case of comparisons.For those functions we want to return the kind as an
int, setting anyPyObject *results through an out pointer.The devguide should document the preferred way to do this, to avoid endless debate for each new C API function.
See python/cpython#105201 (comment) for my preferred approach for three-way return values.
Four and five way return values other than for comparisons are sufficiently uncommon that they can be dealt with on an individual basis.
For comparisons, a slightly strange enum based on powers-of-two is to be used for efficient selection of the desired result by masking.