# PyTime API error handling

See https://github.com/capi-workgroup/decisions/issues/15

- Add pros/cons.
- Add yourself to the proposal(s) if you think we should consider them.
- Remove yourself from proposals if you don't want them (e.g. there's a better proposal)
- Remove proposals with no names left (i.e. ones no one wants).

This is *not* a place for discussion; use GitHub/Discord/Discourse for that.

## Naming

Bikeshed the name too:

### `Unchecked` suffix

cons:
- Not true; the result is checked

### `NoGIL` suffix

(@encukou)

### `Unlocked` suffix
### `NoException` suffix

(@vstinner)

### `Raw` suffix

(Guido, @encukou)

### `PyOS_` prefix

(Steve)

## Examples of errors

* RuntimeError: QueryPerformanceFrequency() returns an invalid frequency.
* RuntimeError: mach_timebase_info() returns an invalid value.
* PermissionError: clock_gettime() fails with EACCESS or EPERM. Can happen in a sandbox.
* OverflowError: fail to convert clock result to PyTime_t. For example, overflow on converting 64-bit time_t seconds (in timeval or timespec) to nanoseconds.
* (unlikely) OSError: other clock_gettime() errors.

## "Unchecked" variants; return -1 on error

(@zooba, @encukou, @vstinner)

``int PyTime_TimeUnchecked(PyTime_t *result)``

(To get exception details, the caller needs to acquire the GIL and re-try with `PyTime_Time`.)

Example logging an unraisable exception with the GIL if getting the time fails:

// Function called without holding the GIL
PyTime_t get_time(void)
{
    PyTime_t t;
    if (PyTime_TimeUnchecked(&t) < 0) {
        // Get the GIL to call PyTime_Time()
        PyGILState_STATE state = PyGILState_Ensure();
        if (PyTime_Time(&t) < 0) {
            // Handle the exception:
            // log an unraisable exception.
            PyErr_FormatUnraisable("failed to get time");
            t = 0;
        }
        PyGILState_Release(gstate);
    }
    return t;
}

### Pros
- doesn't require the GIL
- maybe: doesn't require initialized runtime
- doesn't conflate valid return values with error codes
- doesn't require caller to check for errors
- allows caller to check for errors

### Cons

- No information about reason for failure
- No clear existing use case
- Doesn't distinguish overflow from other errors

## "Unchecked" variants; return errno

(@zooba)

``int PyTime_Time(PyTime_t *result)``

### Pros
- doesn't require the GIL

### Cons

- An *errno* is not always available.
- No clear existing use case.
- If we don't use errno, we need to maintain our own list of error codes which can cause some maintaince burden for the stable ABI.

## Require the GIL (current main branch)

(@encukou, @zooba)

### Pros
- simple API (no new functions)

### Cons
- Having to acquire the GIL just to get the time in a cross-platform way seems … excessive.

## Rejected APIs

### Return PyTime_t with error argument

API: ``PyTime_t PyTime_TimeUnchecked(int *error)``

* Set error to 0 and return time on success.
* Set error to 1 and return 0 on error.
* error can be NULL.

On error, call again PyTime_Time() to get a regular Python exception with a nice type and error message.

Example:

// Function called without holding the GIL
PyTime_t benchmark(void (*func)(void))
{
    PyTime_t t1 = PyTime_TimeUnchecked(NULL);
    func();
    PyTime_t t2 = PyTime_TimeUnchecked(NULL);
    return t2 - 1;
}

Example:

// Function called without holding the GIL
void get_time(void)
{
    int failed;
    PyTime_t t = PyTime_TimeUnchecked(&failed);
    if (failed) {
        // Get the GIL to call PyTime_Time()
        PyGILState_STATE state = PyGILState_Ensure();
        if (PyTime_Time(&t) < 0) {
            // Handle the exception: log an unraisable
            // exception.
            PyErr_FormatUnraisable("failed to get time");
        }
        else {
            failed = 0;
        }
        PyGILState_Release(gstate);
    }
    if (!failed) {
        printf("current time is %lld\n", (long long)t);
    }
}

#### Pros
- return value is directly time: it's more convenient (see the benchmark example).
- doesn't require caller to check for errors.
- errors are not silently ignored, unless the caller pass NULL on purpose.

### Cons
- caller doesn't know the error cause, only that the function failed.
- No clear existing use case

### Log unraisable exception

API: ``PyTime_t PyTime_TimeUnchecked(void)``

**Change** PyTime to not report errors to the caller, but **log** errors as an **unraisable exception** (logged by `sys.unraisablehook`, to stderr by default) and return 0 on error. Acquire the GIL to raise an exception and then log it, then release the GIL. So the common case remains efficient: don't touch the GIL. The caller doesn't need to hold the GIL.

#### Pros
- doesn't require caller to check for errors

#### Cons
- Errors can pass silently
- No clear existing use case
- Acquires the GIL internally (in the unlikely error case)