include/python3.13/ceval.h

0001 /* Interface to random parts in ceval.c */
0002
0003 #ifndef Py_CEVAL_H
0004 #define Py_CEVAL_H
0005 #ifdef __cplusplus
0006 extern "C" {
0007 #endif
0008
0009
0010 PyAPI_FUNC(PyObject *) PyEval_EvalCode(PyObject *, PyObject *, PyObject *);
0011
0012 PyAPI_FUNC(PyObject *) PyEval_EvalCodeEx(PyObject *co,
0013                                          PyObject *globals,
0014                                          PyObject *locals,
0015                                          PyObject *const *args, int argc,
0016                                          PyObject *const *kwds, int kwdc,
0017                                          PyObject *const *defs, int defc,
0018                                          PyObject *kwdefs, PyObject *closure);
0019
0020 PyAPI_FUNC(PyObject *) PyEval_GetBuiltins(void);
0021 PyAPI_FUNC(PyObject *) PyEval_GetGlobals(void);
0022 PyAPI_FUNC(PyObject *) PyEval_GetLocals(void);
0023 PyAPI_FUNC(PyFrameObject *) PyEval_GetFrame(void);
0024
0025 PyAPI_FUNC(PyObject *) PyEval_GetFrameBuiltins(void);
0026 PyAPI_FUNC(PyObject *) PyEval_GetFrameGlobals(void);
0027 PyAPI_FUNC(PyObject *) PyEval_GetFrameLocals(void);
0028
0029 PyAPI_FUNC(int) Py_AddPendingCall(int (*func)(void *), void *arg);
0030 PyAPI_FUNC(int) Py_MakePendingCalls(void);
0031
0032 /* Protection against deeply nested recursive calls
0033
0034    In Python 3.0, this protection has two levels:
0035    * normal anti-recursion protection is triggered when the recursion level
0036      exceeds the current recursion limit. It raises a RecursionError, and sets
0037      the "overflowed" flag in the thread state structure. This flag
0038      temporarily *disables* the normal protection; this allows cleanup code
0039      to potentially outgrow the recursion limit while processing the
0040      RecursionError.
0041    * "last chance" anti-recursion protection is triggered when the recursion
0042      level exceeds "current recursion limit + 50". By construction, this
0043      protection can only be triggered when the "overflowed" flag is set. It
0044      means the cleanup code has itself gone into an infinite loop, or the
0045      RecursionError has been mistakingly ignored. When this protection is
0046      triggered, the interpreter aborts with a Fatal Error.
0047
0048    In addition, the "overflowed" flag is automatically reset when the
0049    recursion level drops below "current recursion limit - 50". This heuristic
0050    is meant to ensure that the normal anti-recursion protection doesn't get
0051    disabled too long.
0052
0053    Please note: this scheme has its own limitations. See:
0054    http://mail.python.org/pipermail/python-dev/2008-August/082106.html
0055    for some observations.
0056 */
0057 PyAPI_FUNC(void) Py_SetRecursionLimit(int);
0058 PyAPI_FUNC(int) Py_GetRecursionLimit(void);
0059
0060 PyAPI_FUNC(int) Py_EnterRecursiveCall(const char *where);
0061 PyAPI_FUNC(void) Py_LeaveRecursiveCall(void);
0062
0063 PyAPI_FUNC(const char *) PyEval_GetFuncName(PyObject *);
0064 PyAPI_FUNC(const char *) PyEval_GetFuncDesc(PyObject *);
0065
0066 PyAPI_FUNC(PyObject *) PyEval_EvalFrame(PyFrameObject *);
0067 PyAPI_FUNC(PyObject *) PyEval_EvalFrameEx(PyFrameObject *f, int exc);
0068
0069 /* Interface for threads.
0070
0071    A module that plans to do a blocking system call (or something else
0072    that lasts a long time and doesn't touch Python data) can allow other
0073    threads to run as follows:
0074
0075     ...preparations here...
0076     Py_BEGIN_ALLOW_THREADS
0077     ...blocking system call here...
0078     Py_END_ALLOW_THREADS
0079     ...interpret result here...
0080
0081    The Py_BEGIN_ALLOW_THREADS/Py_END_ALLOW_THREADS pair expands to a
0082    {}-surrounded block.
0083    To leave the block in the middle (e.g., with return), you must insert
0084    a line containing Py_BLOCK_THREADS before the return, e.g.
0085
0086     if (...premature_exit...) {
0087         Py_BLOCK_THREADS
0088         PyErr_SetFromErrno(PyExc_OSError);
0089         return NULL;
0090     }
0091
0092    An alternative is:
0093
0094     Py_BLOCK_THREADS
0095     if (...premature_exit...) {
0096         PyErr_SetFromErrno(PyExc_OSError);
0097         return NULL;
0098     }
0099     Py_UNBLOCK_THREADS
0100
0101    For convenience, that the value of 'errno' is restored across
0102    Py_END_ALLOW_THREADS and Py_BLOCK_THREADS.
0103
0104    WARNING: NEVER NEST CALLS TO Py_BEGIN_ALLOW_THREADS AND
0105    Py_END_ALLOW_THREADS!!!
0106
0107    Note that not yet all candidates have been converted to use this
0108    mechanism!
0109 */
0110
0111 PyAPI_FUNC(PyThreadState *) PyEval_SaveThread(void);
0112 PyAPI_FUNC(void) PyEval_RestoreThread(PyThreadState *);
0113
0114 Py_DEPRECATED(3.9) PyAPI_FUNC(void) PyEval_InitThreads(void);
0115
0116 PyAPI_FUNC(void) PyEval_AcquireThread(PyThreadState *tstate);
0117 PyAPI_FUNC(void) PyEval_ReleaseThread(PyThreadState *tstate);
0118
0119 #define Py_BEGIN_ALLOW_THREADS { \
0120                         PyThreadState *_save; \
0121                         _save = PyEval_SaveThread();
0122 #define Py_BLOCK_THREADS        PyEval_RestoreThread(_save);
0123 #define Py_UNBLOCK_THREADS      _save = PyEval_SaveThread();
0124 #define Py_END_ALLOW_THREADS    PyEval_RestoreThread(_save); \
0125                  }
0126
0127 /* Masks and values used by FORMAT_VALUE opcode. */
0128 #define FVC_MASK      0x3
0129 #define FVC_NONE      0x0
0130 #define FVC_STR       0x1
0131 #define FVC_REPR      0x2
0132 #define FVC_ASCII     0x3
0133 #define FVS_MASK      0x4
0134 #define FVS_HAVE_SPEC 0x4
0135
0136 #ifndef Py_LIMITED_API
0137 #  define Py_CPYTHON_CEVAL_H
0138 #  include "cpython/ceval.h"
0139 #  undef Py_CPYTHON_CEVAL_H
0140 #endif
0141
0142 #ifdef __cplusplus
0143 }
0144 #endif
0145 #endif /* !Py_CEVAL_H */