blob: 966ff1f6e6e38c3c5c552bb22cecb6d468693e93 [file] [log] [blame]
Guido van Rossumf70e43a1991-02-19 12:39:46 +00001
Guido van Rossum3f5da241990-12-20 15:06:42 +00002/* Frame object interface */
3
Martin v. Löwis4d0d4712010-12-03 20:14:31 +00004#ifndef Py_LIMITED_API
Fred Drakeea9cb5a2000-07-09 00:20:36 +00005#ifndef Py_FRAMEOBJECT_H
6#define Py_FRAMEOBJECT_H
7#ifdef __cplusplus
8extern "C" {
9#endif
10
Guido van Rossum3f5da241990-12-20 15:06:42 +000011typedef struct {
Nick Coghlan1f7ce622012-01-13 21:43:40 +100012 int b_type; /* what kind of block this is */
13 int b_handler; /* where to jump to find handler */
14 int b_level; /* value stack level to pop to */
Guido van Rossumcaa63801995-01-12 11:45:45 +000015} PyTryBlock;
Guido van Rossum3f5da241990-12-20 15:06:42 +000016
17typedef struct _frame {
Neil Schemenauer251ead82001-08-29 23:45:25 +000018 PyObject_VAR_HEAD
Nick Coghlan1f7ce622012-01-13 21:43:40 +100019 struct _frame *f_back; /* previous frame, or NULL */
20 PyCodeObject *f_code; /* code segment */
21 PyObject *f_builtins; /* builtin symbol table (PyDictObject) */
22 PyObject *f_globals; /* global symbol table (PyDictObject) */
23 PyObject *f_locals; /* local symbol table (any mapping) */
24 PyObject **f_valuestack; /* points after the last local */
Tim Peters8c963692001-06-23 05:26:56 +000025 /* Next free slot in f_valuestack. Frame creation sets to f_valuestack.
26 Frame evaluation usually NULLs it, but a frame that yields sets it
27 to the current stack top. */
28 PyObject **f_stacktop;
Nick Coghlan1f7ce622012-01-13 21:43:40 +100029 PyObject *f_trace; /* Trace function */
Thomas Wouters477c8d52006-05-27 19:21:47 +000030
Nick Coghlan1f7ce622012-01-13 21:43:40 +100031 /* In a generator, we need to be able to swap between the exception
32 state inside the generator and the exception state of the calling
33 frame (which shouldn't be impacted when the generator "yields"
34 from an except handler).
35 These three fields exist exactly for that, and are unused for
Andrew Svetlovc37cfd62012-12-05 17:59:10 +020036 non-generator frames. See the save_exc_state and swap_exc_state
37 functions in ceval.c for details of their use. */
Fred Drakeea9cb5a2000-07-09 00:20:36 +000038 PyObject *f_exc_type, *f_exc_value, *f_exc_traceback;
Antoine Pitrou236a5472013-08-06 23:06:59 +020039 /* Borrowed reference to a generator, or NULL */
Antoine Pitrou58720d62013-08-05 23:26:40 +020040 PyObject *f_gen;
Thomas Wouters477c8d52006-05-27 19:21:47 +000041
Nick Coghlan1f7ce622012-01-13 21:43:40 +100042 int f_lasti; /* Last instruction if called */
Alexandre Vassalotti7b82b402009-07-21 04:30:03 +000043 /* Call PyFrame_GetLineNumber() instead of reading this field
44 directly. As of 2.3 f_lineno is only valid when tracing is
45 active (i.e. when f_trace is set). At other times we use
46 PyCode_Addr2Line to calculate the line from the current
47 bytecode index. */
Nick Coghlan1f7ce622012-01-13 21:43:40 +100048 int f_lineno; /* Current line number */
49 int f_iblock; /* index in f_blockstack */
Antoine Pitrou58720d62013-08-05 23:26:40 +020050 char f_executing; /* whether the frame is still executing */
Fred Drakeea9cb5a2000-07-09 00:20:36 +000051 PyTryBlock f_blockstack[CO_MAXBLOCKS]; /* for try and loop blocks */
Nick Coghlan1f7ce622012-01-13 21:43:40 +100052 PyObject *f_localsplus[1]; /* locals+stack, dynamically sized */
Guido van Rossumcaa63801995-01-12 11:45:45 +000053} PyFrameObject;
Guido van Rossum3f5da241990-12-20 15:06:42 +000054
55
56/* Standard object interface */
57
Mark Hammond91a681d2002-08-12 07:21:58 +000058PyAPI_DATA(PyTypeObject) PyFrame_Type;
Guido van Rossum3f5da241990-12-20 15:06:42 +000059
Christian Heimes90aa7642007-12-19 02:45:37 +000060#define PyFrame_Check(op) (Py_TYPE(op) == &PyFrame_Type)
Guido van Rossum3f5da241990-12-20 15:06:42 +000061
Mark Hammond91a681d2002-08-12 07:21:58 +000062PyAPI_FUNC(PyFrameObject *) PyFrame_New(PyThreadState *, PyCodeObject *,
Jeremy Hylton30c9f392001-03-13 01:58:22 +000063 PyObject *, PyObject *);
Guido van Rossum3f5da241990-12-20 15:06:42 +000064
65
66/* The rest of the interface is specific for frame objects */
67
Guido van Rossum3f5da241990-12-20 15:06:42 +000068/* Block management functions */
69
Mark Hammond91a681d2002-08-12 07:21:58 +000070PyAPI_FUNC(void) PyFrame_BlockSetup(PyFrameObject *, int, int, int);
71PyAPI_FUNC(PyTryBlock *) PyFrame_BlockPop(PyFrameObject *);
Guido van Rossuma9e7dc11992-10-18 18:53:57 +000072
73/* Extend the value stack */
74
Mark Hammond91a681d2002-08-12 07:21:58 +000075PyAPI_FUNC(PyObject **) PyFrame_ExtendStack(PyFrameObject *, int, int);
Guido van Rossuma3309961993-07-28 09:05:47 +000076
Guido van Rossumb6775db1994-08-01 11:34:53 +000077/* Conversions between "fast locals" and locals in dictionary */
78
Mark Hammond91a681d2002-08-12 07:21:58 +000079PyAPI_FUNC(void) PyFrame_LocalsToFast(PyFrameObject *, int);
Victor Stinner41bb43a2013-10-29 01:19:37 +010080
81PyAPI_FUNC(int) PyFrame_FastToLocalsWithError(PyFrameObject *f);
Mark Hammond91a681d2002-08-12 07:21:58 +000082PyAPI_FUNC(void) PyFrame_FastToLocals(PyFrameObject *);
Guido van Rossumb6775db1994-08-01 11:34:53 +000083
Christian Heimesa156e092008-02-16 07:38:31 +000084PyAPI_FUNC(int) PyFrame_ClearFreeList(void);
85
David Malcolm49526f42012-06-22 14:55:41 -040086PyAPI_FUNC(void) _PyFrame_DebugMallocStats(FILE *out);
87
Alexandre Vassalotti7b82b402009-07-21 04:30:03 +000088/* Return the line of code the frame is currently executing. */
89PyAPI_FUNC(int) PyFrame_GetLineNumber(PyFrameObject *);
90
Guido van Rossuma3309961993-07-28 09:05:47 +000091#ifdef __cplusplus
92}
93#endif
94#endif /* !Py_FRAMEOBJECT_H */
Martin v. Löwis4d0d4712010-12-03 20:14:31 +000095#endif /* Py_LIMITED_API */