python3.13/cpython/code.h

0001 /* Definitions for bytecode */
0002
0003 #ifndef Py_LIMITED_API
0004 #ifndef Py_CODE_H
0005 #define Py_CODE_H
0006
0007 #ifdef __cplusplus
0008 extern "C" {
0009 #endif
0010
0011 /* Count of all local monitoring events */
0012 #define  _PY_MONITORING_LOCAL_EVENTS 10
0013 /* Count of all "real" monitoring events (not derived from other events) */
0014 #define _PY_MONITORING_UNGROUPED_EVENTS 15
0015 /* Count of all  monitoring events */
0016 #define _PY_MONITORING_EVENTS 17
0017
0018 /* Tables of which tools are active for each monitored event. */
0019 typedef struct _Py_LocalMonitors {
0020     uint8_t tools[_PY_MONITORING_LOCAL_EVENTS];
0021 } _Py_LocalMonitors;
0022
0023 typedef struct _Py_GlobalMonitors {
0024     uint8_t tools[_PY_MONITORING_UNGROUPED_EVENTS];
0025 } _Py_GlobalMonitors;
0026
0027
0028 typedef struct {
0029     PyObject *_co_code;
0030     PyObject *_co_varnames;
0031     PyObject *_co_cellvars;
0032     PyObject *_co_freevars;
0033 } _PyCoCached;
0034
0035 /* Ancillary data structure used for instrumentation.
0036    Line instrumentation creates this with sufficient
0037    space for one entry per code unit. The total size
0038    of the data will be `bytes_per_entry * Py_SIZE(code)` */
0039 typedef struct {
0040     uint8_t bytes_per_entry;
0041     uint8_t data[1];
0042 } _PyCoLineInstrumentationData;
0043
0044
0045 typedef struct {
0046     int size;
0047     int capacity;
0048     struct _PyExecutorObject *executors[1];
0049 } _PyExecutorArray;
0050
0051 /* Main data structure used for instrumentation.
0052  * This is allocated when needed for instrumentation
0053  */
0054 typedef struct {
0055     /* Monitoring specific to this code object */
0056     _Py_LocalMonitors local_monitors;
0057     /* Monitoring that is active on this code object */
0058     _Py_LocalMonitors active_monitors;
0059     /* The tools that are to be notified for events for the matching code unit */
0060     uint8_t *tools;
0061     /* Information to support line events */
0062     _PyCoLineInstrumentationData *lines;
0063     /* The tools that are to be notified for line events for the matching code unit */
0064     uint8_t *line_tools;
0065     /* Information to support instruction events */
0066     /* The underlying instructions, which can themselves be instrumented */
0067     uint8_t *per_instruction_opcodes;
0068     /* The tools that are to be notified for instruction events for the matching code unit */
0069     uint8_t *per_instruction_tools;
0070 } _PyCoMonitoringData;
0071
0072 // To avoid repeating ourselves in deepfreeze.py, all PyCodeObject members are
0073 // defined in this macro:
0074 #define _PyCode_DEF(SIZE) {                                                    \
0075     PyObject_VAR_HEAD                                                          \
0076                                                                                \
0077     /* Note only the following fields are used in hash and/or comparisons      \
0078      *                                                                         \
0079      * - co_name                                                               \
0080      * - co_argcount                                                           \
0081      * - co_posonlyargcount                                                    \
0082      * - co_kwonlyargcount                                                     \
0083      * - co_nlocals                                                            \
0084      * - co_stacksize                                                          \
0085      * - co_flags                                                              \
0086      * - co_firstlineno                                                        \
0087      * - co_consts                                                             \
0088      * - co_names                                                              \
0089      * - co_localsplusnames                                                    \
0090      * This is done to preserve the name and line number for tracebacks        \
0091      * and debuggers; otherwise, constant de-duplication would collapse        \
0092      * identical functions/lambdas defined on different lines.                 \
0093      */                                                                        \
0094                                                                                \
0095     /* These fields are set with provided values on new code objects. */       \
0096                                                                                \
0097     /* The hottest fields (in the eval loop) are grouped here at the top. */   \
0098     PyObject *co_consts;           /* list (constants used) */                 \
0099     PyObject *co_names;            /* list of strings (names used) */          \
0100     PyObject *co_exceptiontable;   /* Byte string encoding exception handling  \
0101                                       table */                                 \
0102     int co_flags;                  /* CO_..., see below */                     \
0103                                                                                \
0104     /* The rest are not so impactful on performance. */                        \
0105     int co_argcount;              /* #arguments, except *args */               \
0106     int co_posonlyargcount;       /* #positional only arguments */             \
0107     int co_kwonlyargcount;        /* #keyword only arguments */                \
0108     int co_stacksize;             /* #entries needed for evaluation stack */   \
0109     int co_firstlineno;           /* first source line number */               \
0110                                                                                \
0111     /* redundant values (derived from co_localsplusnames and                   \
0112        co_localspluskinds) */                                                  \
0113     int co_nlocalsplus;           /* number of local + cell + free variables */ \
0114     int co_framesize;             /* Size of frame in words */                 \
0115     int co_nlocals;               /* number of local variables */              \
0116     int co_ncellvars;             /* total number of cell variables */         \
0117     int co_nfreevars;             /* number of free variables */               \
0118     uint32_t co_version;          /* version number */                         \
0119                                                                                \
0120     PyObject *co_localsplusnames; /* tuple mapping offsets to names */         \
0121     PyObject *co_localspluskinds; /* Bytes mapping to local kinds (one byte    \
0122                                      per variable) */                          \
0123     PyObject *co_filename;        /* unicode (where it was loaded from) */     \
0124     PyObject *co_name;            /* unicode (name, for reference) */          \
0125     PyObject *co_qualname;        /* unicode (qualname, for reference) */      \
0126     PyObject *co_linetable;       /* bytes object that holds location info */  \
0127     PyObject *co_weakreflist;     /* to support weakrefs to code objects */    \
0128     _PyExecutorArray *co_executors;      /* executors from optimizer */        \
0129     _PyCoCached *_co_cached;      /* cached co_* attributes */                 \
0130     uintptr_t _co_instrumentation_version; /* current instrumentation version */ \
0131     _PyCoMonitoringData *_co_monitoring; /* Monitoring data */                 \
0132     int _co_firsttraceable;       /* index of first traceable instruction */   \
0133     /* Scratch space for extra data relating to the code object.               \
0134        Type is a void* to keep the format private in codeobject.c to force     \
0135        people to go through the proper APIs. */                                \
0136     void *co_extra;                                                            \
0137     char co_code_adaptive[(SIZE)];                                             \
0138 }
0139
0140 /* Bytecode object */
0141 struct PyCodeObject _PyCode_DEF(1);
0142
0143 /* Masks for co_flags above */
0144 #define CO_OPTIMIZED    0x0001
0145 #define CO_NEWLOCALS    0x0002
0146 #define CO_VARARGS      0x0004
0147 #define CO_VARKEYWORDS  0x0008
0148 #define CO_NESTED       0x0010
0149 #define CO_GENERATOR    0x0020
0150
0151 /* The CO_COROUTINE flag is set for coroutine functions (defined with
0152    ``async def`` keywords) */
0153 #define CO_COROUTINE            0x0080
0154 #define CO_ITERABLE_COROUTINE   0x0100
0155 #define CO_ASYNC_GENERATOR      0x0200
0156
0157 /* bpo-39562: These constant values are changed in Python 3.9
0158    to prevent collision with compiler flags. CO_FUTURE_ and PyCF_
0159    constants must be kept unique. PyCF_ constants can use bits from
0160    0x0100 to 0x10000. CO_FUTURE_ constants use bits starting at 0x20000. */
0161 #define CO_FUTURE_DIVISION      0x20000
0162 #define CO_FUTURE_ABSOLUTE_IMPORT 0x40000 /* do absolute imports by default */
0163 #define CO_FUTURE_WITH_STATEMENT  0x80000
0164 #define CO_FUTURE_PRINT_FUNCTION  0x100000
0165 #define CO_FUTURE_UNICODE_LITERALS 0x200000
0166
0167 #define CO_FUTURE_BARRY_AS_BDFL  0x400000
0168 #define CO_FUTURE_GENERATOR_STOP  0x800000
0169 #define CO_FUTURE_ANNOTATIONS    0x1000000
0170
0171 #define CO_NO_MONITORING_EVENTS 0x2000000
0172
0173 /* This should be defined if a future statement modifies the syntax.
0174    For example, when a keyword is added.
0175 */
0176 #define PY_PARSER_REQUIRES_FUTURE_KEYWORD
0177
0178 #define CO_MAXBLOCKS 21 /* Max static block nesting within a function */
0179
0180 PyAPI_DATA(PyTypeObject) PyCode_Type;
0181
0182 #define PyCode_Check(op) Py_IS_TYPE((op), &PyCode_Type)
0183
0184 static inline Py_ssize_t PyCode_GetNumFree(PyCodeObject *op) {
0185     assert(PyCode_Check(op));
0186     return op->co_nfreevars;
0187 }
0188
0189 static inline int PyUnstable_Code_GetFirstFree(PyCodeObject *op) {
0190     assert(PyCode_Check(op));
0191     return op->co_nlocalsplus - op->co_nfreevars;
0192 }
0193
0194 Py_DEPRECATED(3.13) static inline int PyCode_GetFirstFree(PyCodeObject *op) {
0195     return PyUnstable_Code_GetFirstFree(op);
0196 }
0197
0198 /* Unstable public interface */
0199 PyAPI_FUNC(PyCodeObject *) PyUnstable_Code_New(
0200         int, int, int, int, int, PyObject *, PyObject *,
0201         PyObject *, PyObject *, PyObject *, PyObject *,
0202         PyObject *, PyObject *, PyObject *, int, PyObject *,
0203         PyObject *);
0204
0205 PyAPI_FUNC(PyCodeObject *) PyUnstable_Code_NewWithPosOnlyArgs(
0206         int, int, int, int, int, int, PyObject *, PyObject *,
0207         PyObject *, PyObject *, PyObject *, PyObject *,
0208         PyObject *, PyObject *, PyObject *, int, PyObject *,
0209         PyObject *);
0210         /* same as struct above */
0211 // Old names -- remove when this API changes:
0212 _Py_DEPRECATED_EXTERNALLY(3.12) static inline PyCodeObject *
0213 PyCode_New(
0214         int a, int b, int c, int d, int e, PyObject *f, PyObject *g,
0215         PyObject *h, PyObject *i, PyObject *j, PyObject *k,
0216         PyObject *l, PyObject *m, PyObject *n, int o, PyObject *p,
0217         PyObject *q)
0218 {
0219     return PyUnstable_Code_New(
0220         a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q);
0221 }
0222 _Py_DEPRECATED_EXTERNALLY(3.12) static inline PyCodeObject *
0223 PyCode_NewWithPosOnlyArgs(
0224         int a, int poac, int b, int c, int d, int e, PyObject *f, PyObject *g,
0225         PyObject *h, PyObject *i, PyObject *j, PyObject *k,
0226         PyObject *l, PyObject *m, PyObject *n, int o, PyObject *p,
0227         PyObject *q)
0228 {
0229     return PyUnstable_Code_NewWithPosOnlyArgs(
0230         a, poac, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q);
0231 }
0232
0233 /* Creates a new empty code object with the specified source location. */
0234 PyAPI_FUNC(PyCodeObject *)
0235 PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno);
0236
0237 /* Return the line number associated with the specified bytecode index
0238    in this code object.  If you just need the line number of a frame,
0239    use PyFrame_GetLineNumber() instead. */
0240 PyAPI_FUNC(int) PyCode_Addr2Line(PyCodeObject *, int);
0241
0242 PyAPI_FUNC(int) PyCode_Addr2Location(PyCodeObject *, int, int *, int *, int *, int *);
0243
0244 #define PY_FOREACH_CODE_EVENT(V) \
0245     V(CREATE)                 \
0246     V(DESTROY)
0247
0248 typedef enum {
0249     #define PY_DEF_EVENT(op) PY_CODE_EVENT_##op,
0250     PY_FOREACH_CODE_EVENT(PY_DEF_EVENT)
0251     #undef PY_DEF_EVENT
0252 } PyCodeEvent;
0253
0254
0255 /*
0256  * A callback that is invoked for different events in a code object's lifecycle.
0257  *
0258  * The callback is invoked with a borrowed reference to co, after it is
0259  * created and before it is destroyed.
0260  *
0261  * If the callback sets an exception, it must return -1. Otherwise
0262  * it should return 0.
0263  */
0264 typedef int (*PyCode_WatchCallback)(
0265   PyCodeEvent event,
0266   PyCodeObject* co);
0267
0268 /*
0269  * Register a per-interpreter callback that will be invoked for code object
0270  * lifecycle events.
0271  *
0272  * Returns a handle that may be passed to PyCode_ClearWatcher on success,
0273  * or -1 and sets an error if no more handles are available.
0274  */
0275 PyAPI_FUNC(int) PyCode_AddWatcher(PyCode_WatchCallback callback);
0276
0277 /*
0278  * Clear the watcher associated with the watcher_id handle.
0279  *
0280  * Returns 0 on success or -1 if no watcher exists for the provided id.
0281  */
0282 PyAPI_FUNC(int) PyCode_ClearWatcher(int watcher_id);
0283
0284 /* for internal use only */
0285 struct _opaque {
0286     int computed_line;
0287     const uint8_t *lo_next;
0288     const uint8_t *limit;
0289 };
0290
0291 typedef struct _line_offsets {
0292     int ar_start;
0293     int ar_end;
0294     int ar_line;
0295     struct _opaque opaque;
0296 } PyCodeAddressRange;
0297
0298 /* Update *bounds to describe the first and one-past-the-last instructions in the
0299    same line as lasti.  Return the number of that line.
0300 */
0301 PyAPI_FUNC(int) _PyCode_CheckLineNumber(int lasti, PyCodeAddressRange *bounds);
0302
0303 /* Create a comparable key used to compare constants taking in account the
0304  * object type. It is used to make sure types are not coerced (e.g., float and
0305  * complex) _and_ to distinguish 0.0 from -0.0 e.g. on IEEE platforms
0306  *
0307  * Return (type(obj), obj, ...): a tuple with variable size (at least 2 items)
0308  * depending on the type and the value. The type is the first item to not
0309  * compare bytes and str which can raise a BytesWarning exception. */
0310 PyAPI_FUNC(PyObject*) _PyCode_ConstantKey(PyObject *obj);
0311
0312 PyAPI_FUNC(PyObject*) PyCode_Optimize(PyObject *code, PyObject* consts,
0313                                       PyObject *names, PyObject *lnotab);
0314
0315 PyAPI_FUNC(int) PyUnstable_Code_GetExtra(
0316     PyObject *code, Py_ssize_t index, void **extra);
0317 PyAPI_FUNC(int) PyUnstable_Code_SetExtra(
0318     PyObject *code, Py_ssize_t index, void *extra);
0319 // Old names -- remove when this API changes:
0320 _Py_DEPRECATED_EXTERNALLY(3.12) static inline int
0321 _PyCode_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
0322 {
0323     return PyUnstable_Code_GetExtra(code, index, extra);
0324 }
0325 _Py_DEPRECATED_EXTERNALLY(3.12) static inline int
0326 _PyCode_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
0327 {
0328     return PyUnstable_Code_SetExtra(code, index, extra);
0329 }
0330
0331 /* Equivalent to getattr(code, 'co_code') in Python.
0332    Returns a strong reference to a bytes object. */
0333 PyAPI_FUNC(PyObject *) PyCode_GetCode(PyCodeObject *code);
0334 /* Equivalent to getattr(code, 'co_varnames') in Python. */
0335 PyAPI_FUNC(PyObject *) PyCode_GetVarnames(PyCodeObject *code);
0336 /* Equivalent to getattr(code, 'co_cellvars') in Python. */
0337 PyAPI_FUNC(PyObject *) PyCode_GetCellvars(PyCodeObject *code);
0338 /* Equivalent to getattr(code, 'co_freevars') in Python. */
0339 PyAPI_FUNC(PyObject *) PyCode_GetFreevars(PyCodeObject *code);
0340
0341 typedef enum _PyCodeLocationInfoKind {
0342     /* short forms are 0 to 9 */
0343     PY_CODE_LOCATION_INFO_SHORT0 = 0,
0344     /* one lineforms are 10 to 12 */
0345     PY_CODE_LOCATION_INFO_ONE_LINE0 = 10,
0346     PY_CODE_LOCATION_INFO_ONE_LINE1 = 11,
0347     PY_CODE_LOCATION_INFO_ONE_LINE2 = 12,
0348
0349     PY_CODE_LOCATION_INFO_NO_COLUMNS = 13,
0350     PY_CODE_LOCATION_INFO_LONG = 14,
0351     PY_CODE_LOCATION_INFO_NONE = 15
0352 } _PyCodeLocationInfoKind;
0353
0354 #ifdef __cplusplus
0355 }
0356 #endif
0357 #endif  // !Py_CODE_H
0358 #endif  // !Py_LIMITED_API