Nuitka
The Python compiler
Loading...
Searching...
No Matches
compiled_frame.h
1// Copyright 2025, Kay Hayen, mailto:kay.hayen@gmail.com find license text at end of file
2
3#ifndef __NUITKA_COMPILED_FRAME_H__
4#define __NUITKA_COMPILED_FRAME_H__
5
6/* This file is included from another C file, help IDEs to still parse it on its own. */
7#ifdef __IDE_ONLY__
8#include "nuitka/prelude.h"
9#endif
10
11// Removed flag in 3.11, but we keep code compatible for now. We do not use old
12// value, but 0 because it might get reused. TODO: Probably better to #ifdef
13// usages of it away.
14#if PYTHON_VERSION >= 0x3b0
15#define CO_NOFREE 0
16#endif
17
18// With Python 3.11 or higher, a lightweight object needs to be put into thread
19// state, rather than the full blown frame, that is more similar to current
20// Nuitka frames.
21#if PYTHON_VERSION < 0x3b0
22typedef PyFrameObject Nuitka_ThreadStateFrameType;
23#else
24typedef _PyInterpreterFrame Nuitka_ThreadStateFrameType;
25#endif
26
27// Print a description of given frame objects in frame debug mode
28#if _DEBUG_FRAME
29extern void PRINT_TOP_FRAME(char const *prefix);
30extern void PRINT_PYTHON_FRAME(char const *prefix, PyFrameObject *frame);
31extern void PRINT_COMPILED_FRAME(char const *prefix, struct Nuitka_FrameObject *frame);
32extern void PRINT_INTERPRETER_FRAME(char const *prefix, Nuitka_ThreadStateFrameType *frame);
33#else
34#define PRINT_TOP_FRAME(prefix)
35#define PRINT_PYTHON_FRAME(prefix, frame)
36#define PRINT_COMPILED_FRAME(prefix, frame)
37#define PRINT_INTERPRETER_FRAME(prefix, frame)
38#endif
39
40// Create a frame object for the given code object, frame or module.
41extern struct Nuitka_FrameObject *MAKE_MODULE_FRAME(PyCodeObject *code, PyObject *module);
42extern struct Nuitka_FrameObject *MAKE_FUNCTION_FRAME(PyThreadState *tstate, PyCodeObject *code, PyObject *module,
43 Py_ssize_t locals_size);
44extern struct Nuitka_FrameObject *MAKE_CLASS_FRAME(PyThreadState *tstate, PyCodeObject *code, PyObject *module,
45 PyObject *f_locals, Py_ssize_t locals_size);
46
47// Create a code object for the given filename and function name
48
49#if PYTHON_VERSION < 0x300
50#define MAKE_CODE_OBJECT(filename, line, flags, function_name, function_qualname, arg_names, free_vars, arg_count, \
51 kw_only_count, pos_only_count) \
52 makeCodeObject(filename, line, flags, function_name, arg_names, free_vars, arg_count)
53extern PyCodeObject *makeCodeObject(PyObject *filename, int line, int flags, PyObject *function_name,
54 PyObject *arg_names, PyObject *free_vars, int arg_count);
55#elif PYTHON_VERSION < 0x380
56#define MAKE_CODE_OBJECT(filename, line, flags, function_name, function_qualname, arg_names, free_vars, arg_count, \
57 kw_only_count, pos_only_count) \
58 makeCodeObject(filename, line, flags, function_name, arg_names, free_vars, arg_count, kw_only_count)
59extern PyCodeObject *makeCodeObject(PyObject *filename, int line, int flags, PyObject *function_name,
60 PyObject *arg_names, PyObject *free_vars, int arg_count, int kw_only_count);
61#elif PYTHON_VERSION < 0x3b0
62#define MAKE_CODE_OBJECT(filename, line, flags, function_name, function_qualname, arg_names, free_vars, arg_count, \
63 kw_only_count, pos_only_count) \
64 makeCodeObject(filename, line, flags, function_name, arg_names, free_vars, arg_count, kw_only_count, pos_only_count)
65extern PyCodeObject *makeCodeObject(PyObject *filename, int line, int flags, PyObject *function_name,
66 PyObject *arg_names, PyObject *free_vars, int arg_count, int kw_only_count,
67 int pos_only_count);
68#else
69#define MAKE_CODE_OBJECT(filename, line, flags, function_name, function_qualname, arg_names, free_vars, arg_count, \
70 kw_only_count, pos_only_count) \
71 makeCodeObject(filename, line, flags, function_name, function_qualname, arg_names, free_vars, arg_count, \
72 kw_only_count, pos_only_count)
73extern PyCodeObject *makeCodeObject(PyObject *filename, int line, int flags, PyObject *function_name,
74 PyObject *function_qualname, PyObject *arg_names, PyObject *free_vars,
75 int arg_count, int kw_only_count, int pos_only_count);
76#endif
77
78NUITKA_MAY_BE_UNUSED static inline bool isFakeCodeObject(PyCodeObject *code) {
79#if PYTHON_VERSION < 0x300
80 return code->co_code == const_str_empty;
81#elif PYTHON_VERSION < 0x3b0
82 return code->co_code == const_bytes_empty;
83#else
84 // Starting for Python3.11, we just proper bytecode that raises
85 // "RuntimeError" itself, so this function is only used to
86 // optimize checks away.
87 return false;
88#endif
89}
90
91// Prepare code object for use, patching up its filename.
92extern PyCodeObject *USE_CODE_OBJECT(PyThreadState *tstate, PyObject *code_object, PyObject *module_filename_obj);
93
94extern PyTypeObject Nuitka_Frame_Type;
95
96static inline bool Nuitka_Frame_CheckExact(PyObject *object) {
97 CHECK_OBJECT(object);
98 return Py_TYPE(object) == &Nuitka_Frame_Type;
99}
100
101static inline bool Nuitka_Frame_Check(PyObject *object) {
102 assert(object);
103
104 if (!_PyObject_GC_IS_TRACKED(object)) {
105 return false;
106 }
107
108 CHECK_OBJECT(object);
109
110 if (Nuitka_Frame_CheckExact(object)) {
111 return true;
112 }
113
114 return strcmp(Py_TYPE(object)->tp_name, "compiled_frame") == 0;
115}
116
117struct Nuitka_FrameObject {
118 PyFrameObject m_frame;
119
120#if PYTHON_VERSION >= 0x3b0
121 PyObject *m_generator;
122 PyFrameState m_frame_state;
123 _PyInterpreterFrame m_interpreter_frame;
124
125 // In Python 3.11, the frame object is no longer variable size, and as such
126 // we inherit the wrong kind of header, not PyVarObject, leading to f_back
127 // the PyFrameObject and and ob_size aliasing, which is not good, but we
128 // want to expose the same binary interface, while still being variable size,
129 // so what we do is to preserve the size in this field instead.
130 Py_ssize_t m_ob_size;
131
132#endif
133
134 // Our own extra stuff, attached variables.
135 char const *m_type_description;
136 char m_locals_storage[1];
137};
138
139inline static void CHECK_CODE_OBJECT(PyCodeObject *code_object) { CHECK_OBJECT(code_object); }
140
141NUITKA_MAY_BE_UNUSED static inline bool isFrameUnusable(struct Nuitka_FrameObject *frame_object) {
142 CHECK_OBJECT_X(frame_object);
143
144 bool result =
145 // Never used.
146 frame_object == NULL ||
147 // Still in use
148 Py_REFCNT(frame_object) > 1 ||
149#if PYTHON_VERSION < 0x300
150 // Last used by another thread (TODO: Could just set it when reusing)
151 frame_object->m_frame.f_tstate != PyThreadState_GET() ||
152#endif
153 // Not currently linked.
154 frame_object->m_frame.f_back != NULL;
155
156#if _DEBUG_REFRAME
157 if (result && frame_object != NULL) {
158 PRINT_COMPILED_FRAME("NOT REUSING FRAME:", frame_object);
159 }
160#endif
161
162 return result;
163}
164
165#if _DEBUG_REFCOUNTS
166extern int count_active_frame_cache_instances;
167extern int count_allocated_frame_cache_instances;
168extern int count_released_frame_cache_instances;
169extern int count_hit_frame_cache_instances;
170#endif
171
172#if _DEBUG_FRAME
173extern void dumpFrameStack(void);
174#endif
175
176#if PYTHON_VERSION >= 0x3b0
177inline static PyCodeObject *Nuitka_InterpreterFrame_GetCodeObject(_PyInterpreterFrame *frame) {
178#if PYTHON_VERSION < 0x3d0
179 return frame->f_code;
180#else
181 return (PyCodeObject *)frame->f_executable;
182#endif
183}
184#endif
185
186inline static PyCodeObject *Nuitka_Frame_GetCodeObject(PyFrameObject *frame) {
187#if PYTHON_VERSION >= 0x3b0
188 assert(frame->f_frame);
189 return Nuitka_InterpreterFrame_GetCodeObject(frame->f_frame);
190#else
191 return frame->f_code;
192#endif
193}
194
195inline static void assertPythonFrameObject(PyFrameObject *frame_object) {
196
197 // TODO: Need to do this manually, as this is making frame caching code
198 // vulnerable to mistakes, but so far the compiled frame type is private
199 // assert(PyObject_IsInstance((PyObject *)frame_object, (PyObject *)&PyFrame_Type));
200 CHECK_OBJECT(frame_object);
201
202 CHECK_CODE_OBJECT(Nuitka_Frame_GetCodeObject(frame_object));
203}
204
205inline static void assertFrameObject(struct Nuitka_FrameObject *frame_object) {
206 CHECK_OBJECT(frame_object);
207
208 // TODO: Need to do this manually, as this is making frame caching code
209 // vulnerable to mistakes, but so far the compiled frame type is private
210 // assert(PyObject_IsInstance((PyObject *)frame_object, (PyObject *)&PyFrame_Type));
211
212 assertPythonFrameObject(&frame_object->m_frame);
213}
214
215inline static void assertThreadFrameObject(Nuitka_ThreadStateFrameType *frame) {
216#if PYTHON_VERSION < 0x3b0
217 assertPythonFrameObject(frame);
218#else
219 // For uncompiled frames of Python 3.11 these often do not exist. TODO: Figure
220 // out what to check or how to know it's a compiled one.
221 if (frame->frame_obj) {
222 assertPythonFrameObject(frame->frame_obj);
223 }
224#endif
225}
226
227// Mark frame as currently executed. Starting with Python 3 that means it
228// can or cannot be cleared, or should lead to a generator close. For Python2
229// this is a no-op. Using a define to spare the compile from inlining an empty
230// function.
231#if PYTHON_VERSION >= 0x300
232
233#if PYTHON_VERSION < 0x3b0
234
235static inline void Nuitka_PythonFrame_MarkAsExecuting(PyFrameObject *frame) {
236#if PYTHON_VERSION >= 0x3a0
237 frame->f_state = FRAME_EXECUTING;
238#else
239 frame->f_executing = 1;
240#endif
241}
242
243#endif
244
245static inline void Nuitka_Frame_MarkAsExecuting(struct Nuitka_FrameObject *frame) {
246 CHECK_OBJECT(frame);
247#if PYTHON_VERSION >= 0x3b0
248 frame->m_frame_state = FRAME_EXECUTING;
249#elif PYTHON_VERSION >= 0x3a0
250 frame->m_frame.f_state = FRAME_EXECUTING;
251#else
252 frame->m_frame.f_executing = 1;
253#endif
254}
255#else
256#define Nuitka_Frame_MarkAsExecuting(frame) ;
257#endif
258
259#if PYTHON_VERSION >= 0x300
260static inline void Nuitka_Frame_MarkAsNotExecuting(struct Nuitka_FrameObject *frame) {
261 CHECK_OBJECT(frame);
262#if PYTHON_VERSION >= 0x3b0
263 frame->m_frame_state = FRAME_SUSPENDED;
264#elif PYTHON_VERSION >= 0x3a0
265 frame->m_frame.f_state = FRAME_SUSPENDED;
266#else
267 frame->m_frame.f_executing = 0;
268#endif
269}
270#else
271#define Nuitka_Frame_MarkAsNotExecuting(frame) ;
272#define Nuitka_PythonFrame_MarkAsExecuting(frame) ;
273#endif
274
275#if PYTHON_VERSION >= 0x300
276static inline bool Nuitka_Frame_IsExecuting(struct Nuitka_FrameObject *frame) {
277 CHECK_OBJECT(frame);
278#if PYTHON_VERSION >= 0x3b0
279 return frame->m_frame_state == FRAME_EXECUTING;
280#elif PYTHON_VERSION >= 0x3a0
281 return frame->m_frame.f_state == FRAME_EXECUTING;
282#else
283 return frame->m_frame.f_executing == 1;
284#endif
285}
286#endif
287
288#if PYTHON_VERSION >= 0x3b0
289
290#if PYTHON_VERSION < 0x3d0
291#define CURRENT_TSTATE_INTERPRETER_FRAME(tstate) tstate->cframe->current_frame
292#else
293#define CURRENT_TSTATE_INTERPRETER_FRAME(tstate) tstate->current_frame
294#endif
295
296NUITKA_MAY_BE_UNUSED inline static void pushFrameStackInterpreterFrame(PyThreadState *tstate,
297 _PyInterpreterFrame *interpreter_frame) {
298 _PyInterpreterFrame *old = CURRENT_TSTATE_INTERPRETER_FRAME(tstate);
299 interpreter_frame->previous = old;
300 CURRENT_TSTATE_INTERPRETER_FRAME(tstate) = interpreter_frame;
301
302 if (old != NULL && !_PyFrame_IsIncomplete(old) && interpreter_frame->frame_obj) {
303 interpreter_frame->frame_obj->f_back = old->frame_obj;
304 CHECK_OBJECT_X(old->frame_obj);
305
306 Py_XINCREF(old->frame_obj);
307 }
308}
309#else
310// Put frame at the top of the frame stack and mark as executing.
311NUITKA_MAY_BE_UNUSED inline static void pushFrameStackPythonFrame(PyThreadState *tstate, PyFrameObject *frame_object) {
312 PRINT_TOP_FRAME("Normal push entry top frame:");
313 PRINT_COMPILED_FRAME("Pushing:", frame_object);
314
315 // Make sure it's healthy.
316 assertPythonFrameObject(frame_object);
317
318 PyFrameObject *old = tstate->frame;
319 CHECK_OBJECT_X(old);
320
321 if (old) {
322 assertPythonFrameObject(old);
323 CHECK_CODE_OBJECT(Nuitka_Frame_GetCodeObject(old));
324 }
325
326 // No recursion with identical frames allowed, assert against it.
327 assert(old != frame_object);
328
329 // Push the new frame as the currently active one.
330 tstate->frame = frame_object;
331
332 // Transfer ownership of old frame.
333 if (old != NULL) {
334 frame_object->f_back = old;
335 }
336
337 Nuitka_PythonFrame_MarkAsExecuting(frame_object);
338 Py_INCREF(frame_object);
339
340 PRINT_TOP_FRAME("Normal push exit top frame:");
341}
342#endif
343
344NUITKA_MAY_BE_UNUSED inline static void pushFrameStackCompiledFrame(PyThreadState *tstate,
345 struct Nuitka_FrameObject *frame_object) {
346#if PYTHON_VERSION < 0x3b0
347 pushFrameStackPythonFrame(tstate, &frame_object->m_frame);
348#else
349 pushFrameStackInterpreterFrame(tstate, &frame_object->m_interpreter_frame);
350
351 Nuitka_Frame_MarkAsExecuting(frame_object);
352 Py_INCREF(frame_object);
353#endif
354}
355
356NUITKA_MAY_BE_UNUSED inline static void popFrameStack(PyThreadState *tstate) {
357#if _DEBUG_FRAME
358 PRINT_TOP_FRAME("Normal pop entry top frame:");
359#endif
360
361#if PYTHON_VERSION < 0x3b0
362 struct Nuitka_FrameObject *frame_object = (struct Nuitka_FrameObject *)(tstate->frame);
363 CHECK_OBJECT(frame_object);
364
365#if _DEBUG_FRAME
366 printf("Taking off frame %s %s\n", Nuitka_String_AsString(PyObject_Str((PyObject *)frame_object)),
367 Nuitka_String_AsString(PyObject_Repr((PyObject *)Nuitka_Frame_GetCodeObject(&frame_object->m_frame))));
368#endif
369
370 // Put previous frame on top.
371 tstate->frame = frame_object->m_frame.f_back;
372 frame_object->m_frame.f_back = NULL;
373
374 Nuitka_Frame_MarkAsNotExecuting(frame_object);
375 Py_DECREF(frame_object);
376#else
377 assert(CURRENT_TSTATE_INTERPRETER_FRAME(tstate));
378
379 struct Nuitka_FrameObject *frame_object =
380 (struct Nuitka_FrameObject *)CURRENT_TSTATE_INTERPRETER_FRAME(tstate)->frame_obj;
381 CHECK_OBJECT(frame_object);
382
383 CURRENT_TSTATE_INTERPRETER_FRAME(tstate) = CURRENT_TSTATE_INTERPRETER_FRAME(tstate)->previous;
384
385 Nuitka_Frame_MarkAsNotExecuting(frame_object);
386
387 CHECK_OBJECT_X(frame_object->m_frame.f_back);
388 Py_CLEAR(frame_object->m_frame.f_back);
389
390 Py_DECREF(frame_object);
391
392 frame_object->m_interpreter_frame.previous = NULL;
393#endif
394
395#if _DEBUG_FRAME
396 PRINT_TOP_FRAME("Normal pop exit top frame:");
397#endif
398}
399
400#if PYTHON_VERSION >= 0x300
401NUITKA_MAY_BE_UNUSED static void Nuitka_SetFrameGenerator(struct Nuitka_FrameObject *nuitka_frame,
402 PyObject *generator) {
403#if PYTHON_VERSION < 0x3b0
404 nuitka_frame->m_frame.f_gen = generator;
405#else
406 nuitka_frame->m_generator = generator;
407#endif
408
409 // Mark the frame as executing
410 if (generator) {
411 Nuitka_Frame_MarkAsExecuting(nuitka_frame);
412 }
413}
414#endif
415
416NUITKA_MAY_BE_UNUSED static PyCodeObject *Nuitka_GetFrameCodeObject(struct Nuitka_FrameObject *nuitka_frame) {
417#if PYTHON_VERSION < 0x3b0
418 return nuitka_frame->m_frame.f_code;
419#else
420 return Nuitka_InterpreterFrame_GetCodeObject(&nuitka_frame->m_interpreter_frame);
421#endif
422}
423
424NUITKA_MAY_BE_UNUSED static int Nuitka_GetFrameLineNumber(struct Nuitka_FrameObject *nuitka_frame) {
425 return nuitka_frame->m_frame.f_lineno;
426}
427
428NUITKA_MAY_BE_UNUSED static PyObject **Nuitka_GetCodeVarNames(PyCodeObject *code_object) {
429#if PYTHON_VERSION < 0x3b0
430 return &PyTuple_GET_ITEM(code_object->co_varnames, 0);
431#else
432 // TODO: Might get away with co_names which will be much faster, that functions
433 // that build a new tuple, that we would have to keep around, but it might be
434 // merged with closure variable names, etc. as as such might become wrong.
435 return &PyTuple_GET_ITEM(code_object->co_localsplusnames, 0);
436#endif
437}
438
439// Attach locals to a frame object. TODO: Upper case, this is for generated code only.
440extern void Nuitka_Frame_AttachLocals(struct Nuitka_FrameObject *frame, char const *type_description, ...);
441
442NUITKA_MAY_BE_UNUSED static Nuitka_ThreadStateFrameType *_Nuitka_GetThreadStateFrame(PyThreadState *tstate) {
443#if PYTHON_VERSION < 0x3b0
444 return tstate->frame;
445#else
446 return CURRENT_TSTATE_INTERPRETER_FRAME(tstate);
447#endif
448}
449
450NUITKA_MAY_BE_UNUSED inline static void pushFrameStackGenerator(PyThreadState *tstate,
451 Nuitka_ThreadStateFrameType *frame_object) {
452#if PYTHON_VERSION < 0x3b0
453 Nuitka_ThreadStateFrameType *return_frame = _Nuitka_GetThreadStateFrame(tstate);
454
455 Py_XINCREF(return_frame);
456 // Put the generator back on the frame stack.
457 pushFrameStackPythonFrame(tstate, frame_object);
458 Py_DECREF(frame_object);
459#else
460 pushFrameStackInterpreterFrame(tstate, frame_object);
461#endif
462}
463
464NUITKA_MAY_BE_UNUSED inline static void pushFrameStackGeneratorCompiledFrame(PyThreadState *tstate,
465 struct Nuitka_FrameObject *frame_object) {
466#if PYTHON_VERSION < 0x3b0
467 pushFrameStackGenerator(tstate, &frame_object->m_frame);
468#else
469 pushFrameStackGenerator(tstate, &frame_object->m_interpreter_frame);
470#endif
471}
472
473// Codes used for type_description.
474#define NUITKA_TYPE_DESCRIPTION_NULL 'N'
475#define NUITKA_TYPE_DESCRIPTION_CELL 'c'
476#define NUITKA_TYPE_DESCRIPTION_OBJECT 'o'
477#define NUITKA_TYPE_DESCRIPTION_OBJECT_PTR 'O'
478#define NUITKA_TYPE_DESCRIPTION_BOOL 'b'
479#define NUITKA_TYPE_DESCRIPTION_NILONG 'L'
480
481#if _DEBUG_REFCOUNTS
482extern int count_active_Nuitka_Frame_Type;
483extern int count_allocated_Nuitka_Frame_Type;
484extern int count_released_Nuitka_Frame_Type;
485#endif
486
487#endif
488
489// Part of "Nuitka", an optimizing Python compiler that is compatible and
490// integrates with CPython, but also works on its own.
491//
492// Licensed under the Apache License, Version 2.0 (the "License");
493// you may not use this file except in compliance with the License.
494// You may obtain a copy of the License at
495//
496// http://www.apache.org/licenses/LICENSE-2.0
497//
498// Unless required by applicable law or agreed to in writing, software
499// distributed under the License is distributed on an "AS IS" BASIS,
500// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
501// See the License for the specific language governing permissions and
502// limitations under the License.
Nuitka_FrameObject
Definition compiled_frame.h:117