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