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