/Include/frameobject.h

  1
  2/* Frame object interface */
  3
  4#ifndef Py_FRAMEOBJECT_H
  5#define Py_FRAMEOBJECT_H
  6#ifdef __cplusplus
  7extern "C" {
  8#endif
  9
 10typedef struct PyTryBlock {
 11    int b_type;			/* what kind of block this is */
 12    int b_handler;		/* where to jump to find handler */
 13    int b_level;		/* value stack level to pop to */
 14} PyTryBlock;
 15
 16/* Keep this in sync with Util/PyTypeBuilder.h. */
 17typedef struct _frame {
 18    PyObject_VAR_HEAD
 19    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 */
 25    /* 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;
 29    PyObject *f_trace;		/* Trace function */
 30
 31    /* If an exception is raised in this frame, the next three are used to
 32     * record the exception info (if any) originally in the thread state.  See
 33     * comments before set_exc_info() -- it's not obvious.
 34     * Invariant:  if _type is NULL, then so are _value and _traceback.
 35     * Desired invariant:  all three are NULL, or all three are non-NULL.  That
 36     * one isn't currently true, but "should be".
 37     */
 38    PyObject *f_exc_type, *f_exc_value, *f_exc_traceback;
 39
 40    PyThreadState *f_tstate;
 41    /* When running through the bytecode interpreter, f_lasti records
 42       the index of the most recent instruction to start executing.
 43       It's used to resume generators, to let tracers change the
 44       current line number, and to look up the current line number
 45       through co_lnotab (See PyCode_Addr2Line).  Under LLVM, f_lasti
 46       is a negative number used to index basic blocks that we might
 47       want to resume from (for generators and line changes within
 48       tracing functions).  When f_lasti is negative (and hence
 49       meaningless), f_lineno is correct.  f_lasti is initialized to
 50       -1 when a function is first entered. */
 51    int f_lasti;
 52
 53#ifdef WITH_LLVM
 54    /* At frame creation-time, we snapshot the state of f_code->co_use_jit.
 55       Without this, Python code can cause active generators to flip between
 56       LLVM and the interpreter at will, which is a bad idea. */
 57    int f_use_jit;
 58#endif
 59
 60    /* Call PyFrame_GetLineNumber() instead of reading this field
 61       directly.  As of Unladen Swallow 2009Q2 f_lineno is valid when
 62       tracing is active (i.e. when f_trace is set) and when f_lasti
 63       is negative.  At other times we use PyCode_Addr2Line to
 64       calculate the line from the current bytecode index. */
 65    int f_lineno;		/* Current line number */
 66    unsigned char f_throwflag;	/* true if generator.throw() was called */
 67    unsigned char f_iblock;	/* index in f_blockstack */
 68
 69#ifdef WITH_LLVM
 70    /* Holds a value from _PyFrameBailReason describing if we've
 71       bailed back from JITted code to the interpreter loop and
 72       why. */
 73    unsigned char f_bailed_from_llvm;
 74    unsigned char f_guard_type;
 75#endif
 76
 77    PyTryBlock f_blockstack[CO_MAXBLOCKS]; /* for try and loop blocks */
 78    PyObject *f_localsplus[1];	/* locals+stack, dynamically sized */
 79} PyFrameObject;
 80
 81typedef enum _PyFrameBailReason {
 82    _PYFRAME_NO_BAIL,
 83    _PYFRAME_TRACE_ON_ENTRY,
 84    _PYFRAME_LINE_TRACE,
 85    _PYFRAME_BACKEDGE_TRACE,
 86    _PYFRAME_CALL_PROFILE,
 87    /* Fatal guard failures invalidate the machine code. */
 88    _PYFRAME_FATAL_GUARD_FAIL,
 89    _PYFRAME_GUARD_FAIL,
 90} _PyFrameBailReason;
 91
 92enum _PyFrameGuardType {
 93    _PYGUARD_DEFAULT = 0,
 94    _PYGUARD_BINOP,
 95    _PYGUARD_ATTR,
 96    _PYGUARD_CFUNC,
 97    _PYGUARD_BRANCH,
 98    _PYGUARD_STORE_SUBSCR,
 99    _PYGUARD_LOAD_METHOD,
100    _PYGUARD_CALL_METHOD,
101};
102
103/* Standard object interface */
104
105PyAPI_DATA(PyTypeObject) PyFrame_Type;
106
107#define PyFrame_Check(op) ((op)->ob_type == &PyFrame_Type)
108#define PyFrame_IsRestricted(f) \
109	((f)->f_builtins != (f)->f_tstate->interp->builtins)
110
111PyAPI_FUNC(PyFrameObject *) PyFrame_New(PyThreadState *, PyCodeObject *,
112                                       PyObject *, PyObject *);
113
114
115/* The rest of the interface is specific for frame objects */
116
117/* Block management functions */
118
119PyAPI_FUNC(void) PyFrame_BlockSetup(PyFrameObject *, int, int, int);
120PyAPI_FUNC(PyTryBlock *) PyFrame_BlockPop(PyFrameObject *);
121
122/* Extend the value stack */
123
124PyAPI_FUNC(PyObject **) PyFrame_ExtendStack(PyFrameObject *, int, int);
125
126/* Conversions between "fast locals" and locals in dictionary */
127
128PyAPI_FUNC(void) PyFrame_LocalsToFast(PyFrameObject *, int);
129PyAPI_FUNC(void) PyFrame_FastToLocals(PyFrameObject *);
130
131PyAPI_FUNC(int) PyFrame_ClearFreeList(void);
132
133/* Return the line of code the frame is currently executing. */
134PyAPI_FUNC(int) PyFrame_GetLineNumber(PyFrameObject *);
135
136#ifdef __cplusplus
137}
138#endif
139#endif /* !Py_FRAMEOBJECT_H */