LCOV - code coverage report
Current view: | top level - Include/cpython - funcobject.h (source / functions) |  |  | Hit | Total | Coverage
Test: | CPython 3.12 LCOV report [commit 5e6661bce9] |  | Lines: | 2 | 4 | 50.0 %
Date: | 2023-03-20 08:15:36 |  | Functions: | 1 | 2 | 50.0 %
|  |  | Branches: | 0 | 0 | -

               Branch data     Line data    Source code
           1                 :            : /* Function object interface */
           2                 :            :
           3                 :            : #ifndef Py_LIMITED_API
           4                 :            : #ifndef Py_FUNCOBJECT_H
           5                 :            : #define Py_FUNCOBJECT_H
           6                 :            : #ifdef __cplusplus
           7                 :            : extern "C" {
           8                 :            : #endif
           9                 :            :
          10                 :            :
          11                 :            : #define COMMON_FIELDS(PREFIX) \
          12                 :            :     PyObject *PREFIX ## globals; \
          13                 :            :     PyObject *PREFIX ## builtins; \
          14                 :            :     PyObject *PREFIX ## name; \
          15                 :            :     PyObject *PREFIX ## qualname; \
          16                 :            :     PyObject *PREFIX ## code;        /* A code object, the __code__ attribute */ \
          17                 :            :     PyObject *PREFIX ## defaults;    /* NULL or a tuple */ \
          18                 :            :     PyObject *PREFIX ## kwdefaults;  /* NULL or a dict */ \
          19                 :            :     PyObject *PREFIX ## closure;     /* NULL or a tuple of cell objects */
          20                 :            :
          21                 :            : typedef struct {
          22                 :            :     COMMON_FIELDS(fc_)
          23                 :            : } PyFrameConstructor;
          24                 :            :
          25                 :            : /* Function objects and code objects should not be confused with each other:
          26                 :            :  *
          27                 :            :  * Function objects are created by the execution of the 'def' statement.
          28                 :            :  * They reference a code object in their __code__ attribute, which is a
          29                 :            :  * purely syntactic object, i.e. nothing more than a compiled version of some
          30                 :            :  * source code lines.  There is one code object per source code "fragment",
          31                 :            :  * but each code object can be referenced by zero or many function objects
          32                 :            :  * depending only on how many times the 'def' statement in the source was
          33                 :            :  * executed so far.
          34                 :            :  */
          35                 :            :
          36                 :            : typedef struct {
          37                 :            :     PyObject_HEAD
          38                 :            :     COMMON_FIELDS(func_)
          39                 :            :     PyObject *func_doc;         /* The __doc__ attribute, can be anything */
          40                 :            :     PyObject *func_dict;        /* The __dict__ attribute, a dict or NULL */
          41                 :            :     PyObject *func_weakreflist; /* List of weak references */
          42                 :            :     PyObject *func_module;      /* The __module__ attribute, can be anything */
          43                 :            :     PyObject *func_annotations; /* Annotations, a dict or NULL */
          44                 :            :     vectorcallfunc vectorcall;
          45                 :            :     /* Version number for use by specializer.
          46                 :            :      * Can set to non-zero when we want to specialize.
          47                 :            :      * Will be set to zero if any of these change:
          48                 :            :      *     defaults
          49                 :            :      *     kwdefaults (only if the object changes, not the contents of the dict)
          50                 :            :      *     code
          51                 :            :      *     annotations
          52                 :            :      *     vectorcall function pointer */
          53                 :            :     uint32_t func_version;
          54                 :            :
          55                 :            :     /* Invariant:
          56                 :            :      *     func_closure contains the bindings for func_code->co_freevars, so
          57                 :            :      *     PyTuple_Size(func_closure) == PyCode_GetNumFree(func_code)
          58                 :            :      *     (func_closure may be NULL if PyCode_GetNumFree(func_code) == 0).
          59                 :            :      */
          60                 :            : } PyFunctionObject;
          61                 :            :
          62                 :            : PyAPI_DATA(PyTypeObject) PyFunction_Type;
          63                 :            :
          64                 :            : #define PyFunction_Check(op) Py_IS_TYPE((op), &PyFunction_Type)
          65                 :            :
          66                 :            : PyAPI_FUNC(PyObject *) PyFunction_New(PyObject *, PyObject *);
          67                 :            : PyAPI_FUNC(PyObject *) PyFunction_NewWithQualName(PyObject *, PyObject *, PyObject *);
          68                 :            : PyAPI_FUNC(PyObject *) PyFunction_GetCode(PyObject *);
          69                 :            : PyAPI_FUNC(PyObject *) PyFunction_GetGlobals(PyObject *);
          70                 :            : PyAPI_FUNC(PyObject *) PyFunction_GetModule(PyObject *);
          71                 :            : PyAPI_FUNC(PyObject *) PyFunction_GetDefaults(PyObject *);
          72                 :            : PyAPI_FUNC(int) PyFunction_SetDefaults(PyObject *, PyObject *);
          73                 :            : PyAPI_FUNC(void) PyFunction_SetVectorcall(PyFunctionObject *, vectorcallfunc);
          74                 :            : PyAPI_FUNC(PyObject *) PyFunction_GetKwDefaults(PyObject *);
          75                 :            : PyAPI_FUNC(int) PyFunction_SetKwDefaults(PyObject *, PyObject *);
          76                 :            : PyAPI_FUNC(PyObject *) PyFunction_GetClosure(PyObject *);
          77                 :            : PyAPI_FUNC(int) PyFunction_SetClosure(PyObject *, PyObject *);
          78                 :            : PyAPI_FUNC(PyObject *) PyFunction_GetAnnotations(PyObject *);
          79                 :            : PyAPI_FUNC(int) PyFunction_SetAnnotations(PyObject *, PyObject *);
          80                 :            :
          81                 :            : PyAPI_FUNC(PyObject *) _PyFunction_Vectorcall(
          82                 :            :     PyObject *func,
          83                 :            :     PyObject *const *stack,
          84                 :            :     size_t nargsf,
          85                 :            :     PyObject *kwnames);
          86                 :            :
          87                 :            : #define _PyFunction_CAST(func) \
          88                 :            :     (assert(PyFunction_Check(func)), _Py_CAST(PyFunctionObject*, func))
          89                 :            :
          90                 :            : /* Static inline functions for direct access to these values.
          91                 :            :    Type checks are *not* done, so use with care. */
          92                 :     293906 : static inline PyObject* PyFunction_GET_CODE(PyObject *func) {
          93                 :     293906 :     return _PyFunction_CAST(func)->func_code;
          94                 :            : }
          95                 :            : #define PyFunction_GET_CODE(func) PyFunction_GET_CODE(_PyObject_CAST(func))
          96                 :            :
          97                 :          0 : static inline PyObject* PyFunction_GET_GLOBALS(PyObject *func) {
          98                 :          0 :     return _PyFunction_CAST(func)->func_globals;
          99                 :            : }
         100                 :            : #define PyFunction_GET_GLOBALS(func) PyFunction_GET_GLOBALS(_PyObject_CAST(func))
         101                 :            :
         102                 :            : static inline PyObject* PyFunction_GET_MODULE(PyObject *func) {
         103                 :            :     return _PyFunction_CAST(func)->func_module;
         104                 :            : }
         105                 :            : #define PyFunction_GET_MODULE(func) PyFunction_GET_MODULE(_PyObject_CAST(func))
         106                 :            :
         107                 :            : static inline PyObject* PyFunction_GET_DEFAULTS(PyObject *func) {
         108                 :            :     return _PyFunction_CAST(func)->func_defaults;
         109                 :            : }
         110                 :            : #define PyFunction_GET_DEFAULTS(func) PyFunction_GET_DEFAULTS(_PyObject_CAST(func))
         111                 :            :
         112                 :            : static inline PyObject* PyFunction_GET_KW_DEFAULTS(PyObject *func) {
         113                 :            :     return _PyFunction_CAST(func)->func_kwdefaults;
         114                 :            : }
         115                 :            : #define PyFunction_GET_KW_DEFAULTS(func) PyFunction_GET_KW_DEFAULTS(_PyObject_CAST(func))
         116                 :            :
         117                 :            : static inline PyObject* PyFunction_GET_CLOSURE(PyObject *func) {
         118                 :            :     return _PyFunction_CAST(func)->func_closure;
         119                 :            : }
         120                 :            : #define PyFunction_GET_CLOSURE(func) PyFunction_GET_CLOSURE(_PyObject_CAST(func))
         121                 :            :
         122                 :            : static inline PyObject* PyFunction_GET_ANNOTATIONS(PyObject *func) {
         123                 :            :     return _PyFunction_CAST(func)->func_annotations;
         124                 :            : }
         125                 :            : #define PyFunction_GET_ANNOTATIONS(func) PyFunction_GET_ANNOTATIONS(_PyObject_CAST(func))
         126                 :            :
         127                 :            : /* The classmethod and staticmethod types lives here, too */
         128                 :            : PyAPI_DATA(PyTypeObject) PyClassMethod_Type;
         129                 :            : PyAPI_DATA(PyTypeObject) PyStaticMethod_Type;
         130                 :            :
         131                 :            : PyAPI_FUNC(PyObject *) PyClassMethod_New(PyObject *);
         132                 :            : PyAPI_FUNC(PyObject *) PyStaticMethod_New(PyObject *);
         133                 :            :
         134                 :            : #define PY_FOREACH_FUNC_EVENT(V) \
         135                 :            :     V(CREATE)                    \
         136                 :            :     V(DESTROY)                   \
         137                 :            :     V(MODIFY_CODE)               \
         138                 :            :     V(MODIFY_DEFAULTS)           \
         139                 :            :     V(MODIFY_KWDEFAULTS)
         140                 :            :
         141                 :            : typedef enum {
         142                 :            :     #define PY_DEF_EVENT(EVENT) PyFunction_EVENT_##EVENT,
         143                 :            :     PY_FOREACH_FUNC_EVENT(PY_DEF_EVENT)
         144                 :            :     #undef PY_DEF_EVENT
         145                 :            : } PyFunction_WatchEvent;
         146                 :            :
         147                 :            : /*
         148                 :            :  * A callback that is invoked for different events in a function's lifecycle.
         149                 :            :  *
         150                 :            :  * The callback is invoked with a borrowed reference to func, after it is
         151                 :            :  * created and before it is modified or destroyed. The callback should not
         152                 :            :  * modify func.
         153                 :            :  *
         154                 :            :  * When a function's code object, defaults, or kwdefaults are modified the
         155                 :            :  * callback will be invoked with the respective event and new_value will
         156                 :            :  * contain a borrowed reference to the new value that is about to be stored in
         157                 :            :  * the function. Otherwise the third argument is NULL.
         158                 :            :  *
         159                 :            :  * If the callback returns with an exception set, it must return -1. Otherwise
         160                 :            :  * it should return 0.
         161                 :            :  */
         162                 :            : typedef int (*PyFunction_WatchCallback)(
         163                 :            :   PyFunction_WatchEvent event,
         164                 :            :   PyFunctionObject *func,
         165                 :            :   PyObject *new_value);
         166                 :            :
         167                 :            : /*
         168                 :            :  * Register a per-interpreter callback that will be invoked for function lifecycle
         169                 :            :  * events.
         170                 :            :  *
         171                 :            :  * Returns a handle that may be passed to PyFunction_ClearWatcher on success,
         172                 :            :  * or -1 and sets an error if no more handles are available.
         173                 :            :  */
         174                 :            : PyAPI_FUNC(int) PyFunction_AddWatcher(PyFunction_WatchCallback callback);
         175                 :            :
         176                 :            : /*
         177                 :            :  * Clear the watcher associated with the watcher_id handle.
         178                 :            :  *
         179                 :            :  * Returns 0 on success or -1 if no watcher exists for the supplied id.
         180                 :            :  */
         181                 :            : PyAPI_FUNC(int) PyFunction_ClearWatcher(int watcher_id);
         182                 :            :
         183                 :            : #ifdef __cplusplus
         184                 :            : }
         185                 :            : #endif
         186                 :            : #endif /* !Py_FUNCOBJECT_H */
         187                 :            : #endif /* Py_LIMITED_API */

Generated by: LCOV version 1.14