8.2.3. NBEP 4: Defining C callbacks¶

8.2.3.1. Basic usage¶

We propose adding a new decorator, @cfunc, importable from the main package. This decorator allows defining a callback as in the following example:

from numba import cfunc
from numba.types import float64

# A callback with the C signature `double(double)`

@cfunc(float64(float64), nopython=True)
def integrand(x):
    return 1 / x

The @cfunc decorator returns a “C function” object holding the resources necessary to run the given compiled function (for example its LLVM module). This object has several attributes and methods:

• the ctypes attribute is a ctypes function object representing the native function.
• the address attribute is the address of the native function code, as an integer (note this can also be computed from the ctypes attribute).
• the native_name attribute is the symbol under which the function can be looked up inside the current process.
• the inspect_llvm() method returns the IR for the LLVM module in which the function is compiled. It is expected that the native_name attribute corresponds to the function’s name in the LLVM IR.

The general signature of the decorator is cfunc(signature, **options).

The signature must specify the argument types and return type of the function using Numba types. In contrary to @jit, the return type cannot be omitted.

The options are keyword-only parameters specifying compilation options. We are expecting that the standard @jit options (nopython, forceobj, cache) can be made to work with @cfunc.

8.2.3.2. Passing array data¶

Native platform ABIs as used by C or C++ don’t have the notion of a shaped array as in Numpy. One common solution is to pass a raw data pointer and one or several size arguments (depending on dimensionality). Numba must provide a way to rebuild an array view of this data inside the callback.

from numba import cfunc, carray
from numba.types import float64, CPointer, void, intp

# A callback with the C signature `void(double *, double *, size_t)`

@cfunc(void(CPointer(float64), CPointer(float64), intp))
def invert(in_ptr, out_ptr, n):
    in_ = carray(in_ptr, (n,))
    out = carray(out_ptr, (n,))
    for i in range(n):
        out[i] = 1 / in_[i]

The carray function takes (pointer, shape, dtype) arguments (dtype being optional) and returns a C-layout array view over the data pointer, with the given shape and dtype. pointer must be a ctypes pointer object (not a Python integer). The array’s dimensionality corresponds to the shape tuple’s length. If dtype is not given, the array’s dtype corresponds to the pointer‘s pointee type.

The farray function is similar except that it returns a F-layout array view.

8.2.3.3. Error handling¶

There is no standard mechanism in C for error reporting. Unfortunately, Numba currently doesn’t handle try..except blocks, which makes it more difficult for the user to implement the required error reporting scheme. The current stance of this proposal is to let users guard against invalid arguments where necessary, and do whatever is required to inform the caller of the error.

Based on user feedback, we can later add support for some error reporting schemes, such as returning an integer error code depending on whether an exception was raised, or setting errno.

8.2.3.4. Deferred topics¶