Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/python3.12/cpython/code.h
1 /* Definitions for bytecode */ 2 3 #ifndef Py_LIMITED_API 4 #ifndef Py_CODE_H 5 #define Py_CODE_H 6 7 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 /* Count of all local monitoring events */ 12 #define _PY_MONITORING_LOCAL_EVENTS 10 13 /* Count of all "real" monitoring events (not derived from other events) */ 14 #define _PY_MONITORING_UNGROUPED_EVENTS 15 15 /* Count of all monitoring events */ 16 #define _PY_MONITORING_EVENTS 17 17 18 /* Tables of which tools are active for each monitored event. */ 19 /* For 3.12 ABI compatibility this is over sized */ 20 typedef struct _Py_LocalMonitors { 21 /* Only _PY_MONITORING_LOCAL_EVENTS of these are used */ 22 uint8_t tools[_PY_MONITORING_UNGROUPED_EVENTS]; 23 } _Py_LocalMonitors; 24 25 typedef struct _Py_GlobalMonitors { 26 uint8_t tools[_PY_MONITORING_UNGROUPED_EVENTS]; 27 } _Py_GlobalMonitors; 28 29 /* Each instruction in a code object is a fixed-width value, 30 * currently 2 bytes: 1-byte opcode + 1-byte oparg. The EXTENDED_ARG 31 * opcode allows for larger values but the current limit is 3 uses 32 * of EXTENDED_ARG (see Python/compile.c), for a maximum 33 * 32-bit value. This aligns with the note in Python/compile.c 34 * (compiler_addop_i_line) indicating that the max oparg value is 35 * 2**32 - 1, rather than INT_MAX. 36 */ 37 38 typedef union { 39 uint16_t cache; 40 struct { 41 uint8_t code; 42 uint8_t arg; 43 } op; 44 } _Py_CODEUNIT; 45 46 47 /* These macros only remain defined for compatibility. */ 48 #define _Py_OPCODE(word) ((word).op.code) 49 #define _Py_OPARG(word) ((word).op.arg) 50 51 static inline _Py_CODEUNIT 52 _py_make_codeunit(uint8_t opcode, uint8_t oparg) 53 { 54 // No designated initialisers because of C++ compat 55 _Py_CODEUNIT word; 56 word.op.code = opcode; 57 word.op.arg = oparg; 58 return word; 59 } 60 61 static inline void 62 _py_set_opcode(_Py_CODEUNIT *word, uint8_t opcode) 63 { 64 word->op.code = opcode; 65 } 66 67 #define _Py_MAKE_CODEUNIT(opcode, oparg) _py_make_codeunit((opcode), (oparg)) 68 #define _Py_SET_OPCODE(word, opcode) _py_set_opcode(&(word), (opcode)) 69 70 71 typedef struct { 72 PyObject *_co_code; 73 PyObject *_co_varnames; 74 PyObject *_co_cellvars; 75 PyObject *_co_freevars; 76 } _PyCoCached; 77 78 /* Ancillary data structure used for instrumentation. 79 Line instrumentation creates an array of 80 these. One entry per code unit.*/ 81 typedef struct { 82 uint8_t original_opcode; 83 int8_t line_delta; 84 } _PyCoLineInstrumentationData; 85 86 /* Main data structure used for instrumentation. 87 * This is allocated when needed for instrumentation 88 */ 89 typedef struct { 90 /* Monitoring specific to this code object */ 91 _Py_LocalMonitors local_monitors; 92 /* Monitoring that is active on this code object */ 93 _Py_LocalMonitors active_monitors; 94 /* The tools that are to be notified for events for the matching code unit */ 95 uint8_t *tools; 96 /* Information to support line events */ 97 _PyCoLineInstrumentationData *lines; 98 /* The tools that are to be notified for line events for the matching code unit */ 99 uint8_t *line_tools; 100 /* Information to support instruction events */ 101 /* The underlying instructions, which can themselves be instrumented */ 102 uint8_t *per_instruction_opcodes; 103 /* The tools that are to be notified for instruction events for the matching code unit */ 104 uint8_t *per_instruction_tools; 105 } _PyCoMonitoringData; 106 107 // To avoid repeating ourselves in deepfreeze.py, all PyCodeObject members are 108 // defined in this macro: 109 #define _PyCode_DEF(SIZE) { \ 110 PyObject_VAR_HEAD \ 111 \ 112 /* Note only the following fields are used in hash and/or comparisons \ 113 * \ 114 * - co_name \ 115 * - co_argcount \ 116 * - co_posonlyargcount \ 117 * - co_kwonlyargcount \ 118 * - co_nlocals \ 119 * - co_stacksize \ 120 * - co_flags \ 121 * - co_firstlineno \ 122 * - co_consts \ 123 * - co_names \ 124 * - co_localsplusnames \ 125 * This is done to preserve the name and line number for tracebacks \ 126 * and debuggers; otherwise, constant de-duplication would collapse \ 127 * identical functions/lambdas defined on different lines. \ 128 */ \ 129 \ 130 /* These fields are set with provided values on new code objects. */ \ 131 \ 132 /* The hottest fields (in the eval loop) are grouped here at the top. */ \ 133 PyObject *co_consts; /* list (constants used) */ \ 134 PyObject *co_names; /* list of strings (names used) */ \ 135 PyObject *co_exceptiontable; /* Byte string encoding exception handling \ 136 table */ \ 137 int co_flags; /* CO_..., see below */ \ 138 \ 139 /* The rest are not so impactful on performance. */ \ 140 int co_argcount; /* #arguments, except *args */ \ 141 int co_posonlyargcount; /* #positional only arguments */ \ 142 int co_kwonlyargcount; /* #keyword only arguments */ \ 143 int co_stacksize; /* #entries needed for evaluation stack */ \ 144 int co_firstlineno; /* first source line number */ \ 145 \ 146 /* redundant values (derived from co_localsplusnames and \ 147 co_localspluskinds) */ \ 148 int co_nlocalsplus; /* number of local + cell + free variables */ \ 149 int co_framesize; /* Size of frame in words */ \ 150 int co_nlocals; /* number of local variables */ \ 151 int co_ncellvars; /* total number of cell variables */ \ 152 int co_nfreevars; /* number of free variables */ \ 153 uint32_t co_version; /* version number */ \ 154 \ 155 PyObject *co_localsplusnames; /* tuple mapping offsets to names */ \ 156 PyObject *co_localspluskinds; /* Bytes mapping to local kinds (one byte \ 157 per variable) */ \ 158 PyObject *co_filename; /* unicode (where it was loaded from) */ \ 159 PyObject *co_name; /* unicode (name, for reference) */ \ 160 PyObject *co_qualname; /* unicode (qualname, for reference) */ \ 161 PyObject *co_linetable; /* bytes object that holds location info */ \ 162 PyObject *co_weakreflist; /* to support weakrefs to code objects */ \ 163 _PyCoCached *_co_cached; /* cached co_* attributes */ \ 164 uint64_t _co_instrumentation_version; /* current instrumentation version */ \ 165 _PyCoMonitoringData *_co_monitoring; /* Monitoring data */ \ 166 int _co_firsttraceable; /* index of first traceable instruction */ \ 167 /* Scratch space for extra data relating to the code object. \ 168 Type is a void* to keep the format private in codeobject.c to force \ 169 people to go through the proper APIs. */ \ 170 void *co_extra; \ 171 char co_code_adaptive[(SIZE)]; \ 172 } 173 174 /* Bytecode object */ 175 struct PyCodeObject _PyCode_DEF(1); 176 177 /* Masks for co_flags above */ 178 #define CO_OPTIMIZED 0x0001 179 #define CO_NEWLOCALS 0x0002 180 #define CO_VARARGS 0x0004 181 #define CO_VARKEYWORDS 0x0008 182 #define CO_NESTED 0x0010 183 #define CO_GENERATOR 0x0020 184 185 /* The CO_COROUTINE flag is set for coroutine functions (defined with 186 ``async def`` keywords) */ 187 #define CO_COROUTINE 0x0080 188 #define CO_ITERABLE_COROUTINE 0x0100 189 #define CO_ASYNC_GENERATOR 0x0200 190 191 /* bpo-39562: These constant values are changed in Python 3.9 192 to prevent collision with compiler flags. CO_FUTURE_ and PyCF_ 193 constants must be kept unique. PyCF_ constants can use bits from 194 0x0100 to 0x10000. CO_FUTURE_ constants use bits starting at 0x20000. */ 195 #define CO_FUTURE_DIVISION 0x20000 196 #define CO_FUTURE_ABSOLUTE_IMPORT 0x40000 /* do absolute imports by default */ 197 #define CO_FUTURE_WITH_STATEMENT 0x80000 198 #define CO_FUTURE_PRINT_FUNCTION 0x100000 199 #define CO_FUTURE_UNICODE_LITERALS 0x200000 200 201 #define CO_FUTURE_BARRY_AS_BDFL 0x400000 202 #define CO_FUTURE_GENERATOR_STOP 0x800000 203 #define CO_FUTURE_ANNOTATIONS 0x1000000 204 205 /* This should be defined if a future statement modifies the syntax. 206 For example, when a keyword is added. 207 */ 208 #define PY_PARSER_REQUIRES_FUTURE_KEYWORD 209 210 #define CO_MAXBLOCKS 21 /* Max static block nesting within a function */ 211 212 PyAPI_DATA(PyTypeObject) PyCode_Type; 213 214 #define PyCode_Check(op) Py_IS_TYPE((op), &PyCode_Type) 215 216 static inline Py_ssize_t PyCode_GetNumFree(PyCodeObject *op) { 217 assert(PyCode_Check(op)); 218 return op->co_nfreevars; 219 } 220 221 static inline int PyCode_GetFirstFree(PyCodeObject *op) { 222 assert(PyCode_Check(op)); 223 return op->co_nlocalsplus - op->co_nfreevars; 224 } 225 226 #define _PyCode_CODE(CO) _Py_RVALUE((_Py_CODEUNIT *)(CO)->co_code_adaptive) 227 #define _PyCode_NBYTES(CO) (Py_SIZE(CO) * (Py_ssize_t)sizeof(_Py_CODEUNIT)) 228 229 /* Unstable public interface */ 230 PyAPI_FUNC(PyCodeObject *) PyUnstable_Code_New( 231 int, int, int, int, int, PyObject *, PyObject *, 232 PyObject *, PyObject *, PyObject *, PyObject *, 233 PyObject *, PyObject *, PyObject *, int, PyObject *, 234 PyObject *); 235 236 PyAPI_FUNC(PyCodeObject *) PyUnstable_Code_NewWithPosOnlyArgs( 237 int, int, int, int, int, int, PyObject *, PyObject *, 238 PyObject *, PyObject *, PyObject *, PyObject *, 239 PyObject *, PyObject *, PyObject *, int, PyObject *, 240 PyObject *); 241 /* same as struct above */ 242 // Old names -- remove when this API changes: 243 _Py_DEPRECATED_EXTERNALLY(3.12) static inline PyCodeObject * 244 PyCode_New( 245 int a, int b, int c, int d, int e, PyObject *f, PyObject *g, 246 PyObject *h, PyObject *i, PyObject *j, PyObject *k, 247 PyObject *l, PyObject *m, PyObject *n, int o, PyObject *p, 248 PyObject *q) 249 { 250 return PyUnstable_Code_New( 251 a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q); 252 } 253 _Py_DEPRECATED_EXTERNALLY(3.12) static inline PyCodeObject * 254 PyCode_NewWithPosOnlyArgs( 255 int a, int poac, int b, int c, int d, int e, PyObject *f, PyObject *g, 256 PyObject *h, PyObject *i, PyObject *j, PyObject *k, 257 PyObject *l, PyObject *m, PyObject *n, int o, PyObject *p, 258 PyObject *q) 259 { 260 return PyUnstable_Code_NewWithPosOnlyArgs( 261 a, poac, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q); 262 } 263 264 /* Creates a new empty code object with the specified source location. */ 265 PyAPI_FUNC(PyCodeObject *) 266 PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno); 267 268 /* Return the line number associated with the specified bytecode index 269 in this code object. If you just need the line number of a frame, 270 use PyFrame_GetLineNumber() instead. */ 271 PyAPI_FUNC(int) PyCode_Addr2Line(PyCodeObject *, int); 272 273 PyAPI_FUNC(int) PyCode_Addr2Location(PyCodeObject *, int, int *, int *, int *, int *); 274 275 #define PY_FOREACH_CODE_EVENT(V) \ 276 V(CREATE) \ 277 V(DESTROY) 278 279 typedef enum { 280 #define PY_DEF_EVENT(op) PY_CODE_EVENT_##op, 281 PY_FOREACH_CODE_EVENT(PY_DEF_EVENT) 282 #undef PY_DEF_EVENT 283 } PyCodeEvent; 284 285 286 /* 287 * A callback that is invoked for different events in a code object's lifecycle. 288 * 289 * The callback is invoked with a borrowed reference to co, after it is 290 * created and before it is destroyed. 291 * 292 * If the callback sets an exception, it must return -1. Otherwise 293 * it should return 0. 294 */ 295 typedef int (*PyCode_WatchCallback)( 296 PyCodeEvent event, 297 PyCodeObject* co); 298 299 /* 300 * Register a per-interpreter callback that will be invoked for code object 301 * lifecycle events. 302 * 303 * Returns a handle that may be passed to PyCode_ClearWatcher on success, 304 * or -1 and sets an error if no more handles are available. 305 */ 306 PyAPI_FUNC(int) PyCode_AddWatcher(PyCode_WatchCallback callback); 307 308 /* 309 * Clear the watcher associated with the watcher_id handle. 310 * 311 * Returns 0 on success or -1 if no watcher exists for the provided id. 312 */ 313 PyAPI_FUNC(int) PyCode_ClearWatcher(int watcher_id); 314 315 /* for internal use only */ 316 struct _opaque { 317 int computed_line; 318 const uint8_t *lo_next; 319 const uint8_t *limit; 320 }; 321 322 typedef struct _line_offsets { 323 int ar_start; 324 int ar_end; 325 int ar_line; 326 struct _opaque opaque; 327 } PyCodeAddressRange; 328 329 /* Update *bounds to describe the first and one-past-the-last instructions in the 330 same line as lasti. Return the number of that line. 331 */ 332 PyAPI_FUNC(int) _PyCode_CheckLineNumber(int lasti, PyCodeAddressRange *bounds); 333 334 /* Create a comparable key used to compare constants taking in account the 335 * object type. It is used to make sure types are not coerced (e.g., float and 336 * complex) _and_ to distinguish 0.0 from -0.0 e.g. on IEEE platforms 337 * 338 * Return (type(obj), obj, ...): a tuple with variable size (at least 2 items) 339 * depending on the type and the value. The type is the first item to not 340 * compare bytes and str which can raise a BytesWarning exception. */ 341 PyAPI_FUNC(PyObject*) _PyCode_ConstantKey(PyObject *obj); 342 343 PyAPI_FUNC(PyObject*) PyCode_Optimize(PyObject *code, PyObject* consts, 344 PyObject *names, PyObject *lnotab); 345 346 PyAPI_FUNC(int) PyUnstable_Code_GetExtra( 347 PyObject *code, Py_ssize_t index, void **extra); 348 PyAPI_FUNC(int) PyUnstable_Code_SetExtra( 349 PyObject *code, Py_ssize_t index, void *extra); 350 // Old names -- remove when this API changes: 351 _Py_DEPRECATED_EXTERNALLY(3.12) static inline int 352 _PyCode_GetExtra(PyObject *code, Py_ssize_t index, void **extra) 353 { 354 return PyUnstable_Code_GetExtra(code, index, extra); 355 } 356 _Py_DEPRECATED_EXTERNALLY(3.12) static inline int 357 _PyCode_SetExtra(PyObject *code, Py_ssize_t index, void *extra) 358 { 359 return PyUnstable_Code_SetExtra(code, index, extra); 360 } 361 362 /* Equivalent to getattr(code, 'co_code') in Python. 363 Returns a strong reference to a bytes object. */ 364 PyAPI_FUNC(PyObject *) PyCode_GetCode(PyCodeObject *code); 365 /* Equivalent to getattr(code, 'co_varnames') in Python. */ 366 PyAPI_FUNC(PyObject *) PyCode_GetVarnames(PyCodeObject *code); 367 /* Equivalent to getattr(code, 'co_cellvars') in Python. */ 368 PyAPI_FUNC(PyObject *) PyCode_GetCellvars(PyCodeObject *code); 369 /* Equivalent to getattr(code, 'co_freevars') in Python. */ 370 PyAPI_FUNC(PyObject *) PyCode_GetFreevars(PyCodeObject *code); 371 372 typedef enum _PyCodeLocationInfoKind { 373 /* short forms are 0 to 9 */ 374 PY_CODE_LOCATION_INFO_SHORT0 = 0, 375 /* one lineforms are 10 to 12 */ 376 PY_CODE_LOCATION_INFO_ONE_LINE0 = 10, 377 PY_CODE_LOCATION_INFO_ONE_LINE1 = 11, 378 PY_CODE_LOCATION_INFO_ONE_LINE2 = 12, 379 380 PY_CODE_LOCATION_INFO_NO_COLUMNS = 13, 381 PY_CODE_LOCATION_INFO_LONG = 14, 382 PY_CODE_LOCATION_INFO_NONE = 15 383 } _PyCodeLocationInfoKind; 384 385 #ifdef __cplusplus 386 } 387 #endif 388 #endif // !Py_CODE_H 389 #endif // !Py_LIMITED_API
