Description
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.