diff options
Diffstat (limited to 'doc/source/reference/c-api.ufunc.rst')
| -rw-r--r-- | doc/source/reference/c-api.ufunc.rst | 136 |
1 files changed, 68 insertions, 68 deletions
diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index 3673958d9..ee1822122 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -10,16 +10,16 @@ UFunc API Constants --------- -.. cvar:: UFUNC_ERR_{HANDLER} +.. c:var:: UFUNC_ERR_{HANDLER} ``{HANDLER}`` can be **IGNORE**, **WARN**, **RAISE**, or **CALL** -.. cvar:: UFUNC_{THING}_{ERR} +.. c:var:: UFUNC_{THING}_{ERR} ``{THING}`` can be **MASK**, **SHIFT**, or **FPE**, and ``{ERR}`` can be **DIVIDEBYZERO**, **OVERFLOW**, **UNDERFLOW**, and **INVALID**. -.. cvar:: PyUFunc_{VALUE} +.. c:var:: PyUFunc_{VALUE} ``{VALUE}`` can be **One** (1), **Zero** (0), or **None** (-1) @@ -27,37 +27,37 @@ Constants Macros ------ -.. cmacro:: NPY_LOOP_BEGIN_THREADS +.. c:macro:: NPY_LOOP_BEGIN_THREADS Used in universal function code to only release the Python GIL if loop->obj is not true (*i.e.* this is not an OBJECT array - loop). Requires use of :cmacro:`NPY_BEGIN_THREADS_DEF` in variable + loop). Requires use of :c:macro:`NPY_BEGIN_THREADS_DEF` in variable declaration area. -.. cmacro:: NPY_LOOP_END_THREADS +.. c:macro:: NPY_LOOP_END_THREADS Used in universal function code to re-acquire the Python GIL if it was released (because loop->obj was not true). -.. cfunction:: UFUNC_CHECK_ERROR(loop) +.. c:function:: UFUNC_CHECK_ERROR(loop) A macro used internally to check for errors and goto fail if found. This macro requires a fail label in the current code block. The *loop* variable must have at least members (obj, errormask, and errorobj). If *loop* ->obj is nonzero, then - :cfunc:`PyErr_Occurred` () is called (meaning the GIL must be held). If + :c:func:`PyErr_Occurred` () is called (meaning the GIL must be held). If *loop* ->obj is zero, then if *loop* ->errormask is nonzero, - :cfunc:`PyUFunc_checkfperr` is called with arguments *loop* ->errormask + :c:func:`PyUFunc_checkfperr` is called with arguments *loop* ->errormask and *loop* ->errobj. If the result of this check of the IEEE floating point registers is true then the code redirects to the fail label which must be defined. -.. cfunction:: UFUNC_CHECK_STATUS(ret) +.. c:function:: UFUNC_CHECK_STATUS(ret) Deprecated: use npy_clear_floatstatus from npy_math.h instead. A macro that expands to platform-dependent code. The *ret* - variable can can be any integer. The :cdata:`UFUNC_FPE_{ERR}` bits are + variable can can be any integer. The :c:data:`UFUNC_FPE_{ERR}` bits are set in *ret* according to the status of the corresponding error flags of the floating point processor. @@ -65,7 +65,7 @@ Macros Functions --------- -.. cfunction:: PyObject* PyUFunc_FromFuncAndData(PyUFuncGenericFunction* func, +.. c:function:: PyObject* PyUFunc_FromFuncAndData(PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int check_return) @@ -77,13 +77,13 @@ Functions .. note:: The *func*, *data*, *types*, *name*, and *doc* arguments are not - copied by :cfunc:`PyUFunc_FromFuncAndData`. The caller must ensure + copied by :c:func:`PyUFunc_FromFuncAndData`. The caller must ensure that the memory used by these arrays is not freed as long as the ufunc object is alive. :param func: Must to an array of length *ntypes* containing - :ctype:`PyUFuncGenericFunction` items. These items are pointers to + :c:type:`PyUFuncGenericFunction` items. These items are pointers to functions that actually implement the underlying (element-by-element) function :math:`N` times. @@ -127,7 +127,7 @@ Functions structure and it does get set with this value when the ufunc object is created. -.. cfunction:: PyObject* PyUFunc_FromFuncAndDataAndSignature(PyUFuncGenericFunction* func, +.. c:function:: PyObject* PyUFunc_FromFuncAndDataAndSignature(PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int check_return, char *signature) @@ -142,7 +142,7 @@ Functions to calling PyUFunc_FromFuncAndData. A copy of the string is made, so the passed in buffer can be freed. -.. cfunction:: int PyUFunc_RegisterLoopForType(PyUFuncObject* ufunc, +.. c:function:: int PyUFunc_RegisterLoopForType(PyUFuncObject* ufunc, int usertype, PyUFuncGenericFunction function, int* arg_types, void* data) This function allows the user to register a 1-d loop with an @@ -156,7 +156,7 @@ Functions in as *arg_types* which must be a pointer to memory at least as large as ufunc->nargs. -.. cfunction:: int PyUFunc_RegisterLoopForDescr(PyUFuncObject* ufunc, +.. c:function:: int PyUFunc_RegisterLoopForDescr(PyUFuncObject* ufunc, PyArray_Descr* userdtype, PyUFuncGenericFunction function, PyArray_Descr** arg_dtypes, void* data) @@ -166,7 +166,7 @@ Functions registered for structured array data-dtypes and custom data-types instead of scalar data-types. -.. cfunction:: int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc, +.. c:function:: int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc, PyUFuncGenericFunction newfunc, int* signature, PyUFuncGenericFunction* oldfunc) @@ -174,16 +174,16 @@ Functions already-created *ufunc* with the new 1-d loop newfunc. Return the old 1-d loop function in *oldfunc*. Return 0 on success and -1 on failure. This function works only with built-in types (use - :cfunc:`PyUFunc_RegisterLoopForType` for user-defined types). A + :c:func:`PyUFunc_RegisterLoopForType` for user-defined types). A signature is an array of data-type numbers indicating the inputs followed by the outputs assumed by the 1-d loop. -.. cfunction:: int PyUFunc_GenericFunction(PyUFuncObject* self, +.. c:function:: int PyUFunc_GenericFunction(PyUFuncObject* self, PyObject* args, PyObject* kwds, PyArrayObject** mps) A generic ufunc call. The ufunc is passed in as *self*, the arguments to the ufunc as *args* and *kwds*. The *mps* argument is an array of - :ctype:`PyArrayObject` pointers whose values are discarded and which + :c:type:`PyArrayObject` pointers whose values are discarded and which receive the converted input arguments as well as the ufunc outputs when success is returned. The user is responsible for managing this array and receives a new reference for each array in *mps*. The total @@ -191,26 +191,26 @@ Functions Returns 0 on success, -1 on error. -.. cfunction:: int PyUFunc_checkfperr(int errmask, PyObject* errobj) +.. c:function:: int PyUFunc_checkfperr(int errmask, PyObject* errobj) A simple interface to the IEEE error-flag checking support. The - *errmask* argument is a mask of :cdata:`UFUNC_MASK_{ERR}` bitmasks + *errmask* argument is a mask of :c:data:`UFUNC_MASK_{ERR}` bitmasks indicating which errors to check for (and how to check for them). The *errobj* must be a Python tuple with two elements: a string containing the name which will be used in any communication of error and either a callable Python object (call-back function) - or :cdata:`Py_None`. The callable object will only be used if - :cdata:`UFUNC_ERR_CALL` is set as the desired error checking + or :c:data:`Py_None`. The callable object will only be used if + :c:data:`UFUNC_ERR_CALL` is set as the desired error checking method. This routine manages the GIL and is safe to call even after releasing the GIL. If an error in the IEEE-compatibile hardware is determined a -1 is returned, otherwise a 0 is returned. -.. cfunction:: void PyUFunc_clearfperr() +.. c:function:: void PyUFunc_clearfperr() Clear the IEEE error flags. -.. cfunction:: void PyUFunc_GetPyValues(char* name, int* bufsize, +.. c:function:: void PyUFunc_GetPyValues(char* name, int* bufsize, int* errmask, PyObject** errobj) Get the Python values used for ufunc processing from the @@ -238,37 +238,37 @@ of these functions are suitable for placing directly in the array of functions stored in the functions member of the PyUFuncObject structure. -.. cfunction:: void PyUFunc_f_f_As_d_d(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_f_f_As_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_d_d(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_f_f(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_f_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_g_g(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_g_g(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_F_F_As_D_D(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_F_F_As_D_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_F_F(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_F_F(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_D_D(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_D_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_G_G(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_G_G(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_e_e(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_e_e(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_e_e_As_f_f(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_e_e_As_f_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_e_e_As_d_d(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_e_e_As_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) Type specific, core 1-d functions for ufuncs where each @@ -280,41 +280,41 @@ structure. ``G`` - clongdouble). The argument *func* must support the same signature. The _As_X_X variants assume ndarray's of one data type but cast the values to use an underlying function that takes a - different data type. Thus, :cfunc:`PyUFunc_f_f_As_d_d` uses - ndarrays of data type :cdata:`NPY_FLOAT` but calls out to a + different data type. Thus, :c:func:`PyUFunc_f_f_As_d_d` uses + ndarrays of data type :c:data:`NPY_FLOAT` but calls out to a C-function that takes double and returns double. -.. cfunction:: void PyUFunc_ff_f_As_dd_d(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_ff_f_As_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_ff_f(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_ff_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_dd_d(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_gg_g(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_gg_g(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_FF_F_As_DD_D(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_FF_F_As_DD_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_DD_D(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_DD_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_FF_F(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_FF_F(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_GG_G(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_GG_G(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_ee_e(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_ee_e(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_ee_e_As_ff_f(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_ee_e_As_ff_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_ee_e_As_dd_d(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_ee_e_As_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) Type specific, core 1-d functions for ufuncs where each @@ -327,20 +327,20 @@ structure. of one data type but cast the values at each iteration of the loop to use the underlying function that takes a different data type. -.. cfunction:: void PyUFunc_O_O(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_O_O(char** args, npy_intp* dimensions, npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_OO_O(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_OO_O(char** args, npy_intp* dimensions, npy_intp* steps, void* func) One-input, one-output, and two-input, one-output core 1-d functions - for the :cdata:`NPY_OBJECT` data type. These functions handle reference + for the :c:data:`NPY_OBJECT` data type. These functions handle reference count issues and return early on error. The actual function to call is *func* and it must accept calls with the signature ``(PyObject*) - (PyObject*)`` for :cfunc:`PyUFunc_O_O` or ``(PyObject*)(PyObject *, - PyObject *)`` for :cfunc:`PyUFunc_OO_O`. + (PyObject*)`` for :c:func:`PyUFunc_O_O` or ``(PyObject*)(PyObject *, + PyObject *)`` for :c:func:`PyUFunc_OO_O`. -.. cfunction:: void PyUFunc_O_O_method(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_O_O_method(char** args, npy_intp* dimensions, npy_intp* steps, void* func) This general purpose 1-d core function assumes that *func* is a string @@ -348,7 +348,7 @@ structure. iteration of the loop, the Python obejct is extracted from the array and its *func* method is called returning the result to the output array. -.. cfunction:: void PyUFunc_OO_O_method(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_OO_O_method(char** args, npy_intp* dimensions, npy_intp* steps, void* func) This general purpose 1-d core function assumes that *func* is a @@ -358,14 +358,14 @@ structure. function. The output of the function is stored in the third entry of *args*. -.. cfunction:: void PyUFunc_On_Om(char** args, npy_intp* dimensions, +.. c:function:: void PyUFunc_On_Om(char** args, npy_intp* dimensions, npy_intp* steps, void* func) This is the 1-d core function used by the dynamic ufuncs created by umath.frompyfunc(function, nin, nout). In this case *func* is a - pointer to a :ctype:`PyUFunc_PyFuncData` structure which has definition + pointer to a :c:type:`PyUFunc_PyFuncData` structure which has definition - .. ctype:: PyUFunc_PyFuncData + .. c:type:: PyUFunc_PyFuncData .. code-block:: c @@ -384,11 +384,11 @@ structure. Importing the API ----------------- -.. cvar:: PY_UFUNC_UNIQUE_SYMBOL +.. c:var:: PY_UFUNC_UNIQUE_SYMBOL -.. cvar:: NO_IMPORT_UFUNC +.. c:var:: NO_IMPORT_UFUNC -.. cfunction:: void import_ufunc(void) +.. c:function:: void import_ufunc(void) These are the constants and functions for accessing the ufunc C-API from extension modules in precisely the same way as the @@ -397,17 +397,17 @@ Importing the API extension module). If your extension module is in one file then that is all that is required. The other two constants are useful if your extension module makes use of multiple files. In that - case, define :cdata:`PY_UFUNC_UNIQUE_SYMBOL` to something unique to + case, define :c:data:`PY_UFUNC_UNIQUE_SYMBOL` to something unique to your code and then in source files that do not contain the module initialization function but still need access to the UFUNC API, - define :cdata:`PY_UFUNC_UNIQUE_SYMBOL` to the same name used previously - and also define :cdata:`NO_IMPORT_UFUNC`. + define :c:data:`PY_UFUNC_UNIQUE_SYMBOL` to the same name used previously + and also define :c:data:`NO_IMPORT_UFUNC`. The C-API is actually an array of function pointers. This array is created (and pointed to by a global variable) by import_ufunc. The global variable is either statically defined or allowed to be seen by other files depending on the state of - :cdata:`Py_UFUNC_UNIQUE_SYMBOL` and :cdata:`NO_IMPORT_UFUNC`. + :c:data:`Py_UFUNC_UNIQUE_SYMBOL` and :c:data:`NO_IMPORT_UFUNC`. .. index:: pair: ufunc; C-API |