Skip to content

Document the preferred style for API functions with three, four or five-way returns #1121

Closed as not planned
@markshannon

Description

@markshannon

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.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions