1 #ifndef Py_INTERNAL_INTERP_H
2 #define Py_INTERNAL_INTERP_H
3 #ifdef __cplusplus
4 extern "C" {
5 #endif
6
7 #ifndef Py_BUILD_CORE
8 # error "this header requires Py_BUILD_CORE define"
9 #endif
10
11 #include <stdbool.h> // bool
12
13 #include "pycore_ast_state.h" // struct ast_state
14 #include "pycore_atexit.h" // struct atexit_state
15 #include "pycore_ceval_state.h" // struct _ceval_state
16 #include "pycore_code.h" // struct callable_cache
17 #include "pycore_codecs.h" // struct codecs_state
18 #include "pycore_context.h" // struct _Py_context_state
19 #include "pycore_crossinterp.h" // struct _xidregistry
20 #include "pycore_dict_state.h" // struct _Py_dict_state
21 #include "pycore_dtoa.h" // struct _dtoa_state
22 #include "pycore_exceptions.h" // struct _Py_exc_state
23 #include "pycore_floatobject.h" // struct _Py_float_state
24 #include "pycore_function.h" // FUNC_MAX_WATCHERS
25 #include "pycore_gc.h" // struct _gc_runtime_state
26 #include "pycore_genobject.h" // struct _Py_async_gen_state
27 #include "pycore_global_objects.h"// struct _Py_interp_cached_objects
28 #include "pycore_import.h" // struct _import_state
29 #include "pycore_instruments.h" // _PY_MONITORING_EVENTS
30 #include "pycore_list.h" // struct _Py_list_state
31 #include "pycore_mimalloc.h" // struct _mimalloc_interp_state
32 #include "pycore_object_state.h" // struct _py_object_state
33 #include "pycore_optimizer.h" // _PyOptimizerObject
34 #include "pycore_obmalloc.h" // struct _obmalloc_state
35 #include "pycore_qsbr.h" // struct _qsbr_state
36 #include "pycore_tstate.h" // _PyThreadStateImpl
37 #include "pycore_tuple.h" // struct _Py_tuple_state
38 #include "pycore_typeobject.h" // struct types_state
39 #include "pycore_unicodeobject.h" // struct _Py_unicode_state
40 #include "pycore_warnings.h" // struct _warnings_runtime_state
41
42
43 struct _Py_long_state {
44 int max_str_digits;
45 };
46
47 // Support for stop-the-world events. This exists in both the PyRuntime struct
48 // for global pauses and in each PyInterpreterState for per-interpreter pauses.
49 struct _stoptheworld_state {
50 PyMutex mutex; // Serializes stop-the-world attempts.
51
52 // NOTE: The below fields are protected by HEAD_LOCK(runtime), not by the
53 // above mutex.
54 bool requested; // Set when a pause is requested.
55 bool world_stopped; // Set when the world is stopped.
56 bool is_global; // Set when contained in PyRuntime struct.
57
58 PyEvent stop_event; // Set when thread_countdown reaches zero.
59 Py_ssize_t thread_countdown; // Number of threads that must pause.
60
61 PyThreadState *requester; // Thread that requested the pause (may be NULL).
62 };
63
64 #ifdef Py_GIL_DISABLED
65 // This should be prime but otherwise the choice is arbitrary. A larger value
66 // increases concurrency at the expense of memory.
67 # define NUM_WEAKREF_LIST_LOCKS 127
68 #endif
69
70 /* cross-interpreter data registry */
71
72 /* Tracks some rare events per-interpreter, used by the optimizer to turn on/off
73 specific optimizations. */
74 typedef struct _rare_events {
75 /* Setting an object's class, obj.__class__ = ... */
76 uint8_t set_class;
77 /* Setting the bases of a class, cls.__bases__ = ... */
78 uint8_t set_bases;
79 /* Setting the PEP 523 frame eval function, _PyInterpreterState_SetFrameEvalFunc() */
80 uint8_t set_eval_frame_func;
81 /* Modifying the builtins, __builtins__.__dict__[var] = ... */
82 uint8_t builtin_dict;
83 /* Modifying a function, e.g. func.__defaults__ = ..., etc. */
84 uint8_t func_modification;
85 } _rare_events;
86
87 /* interpreter state */
88
89 /* PyInterpreterState holds the global state for one of the runtime's
90 interpreters. Typically the initial (main) interpreter is the only one.
91
92 The PyInterpreterState typedef is in Include/pytypedefs.h.
93 */
94 struct _is {
95
96 /* This struct contains the eval_breaker,
97 * which is by far the hottest field in this struct
98 * and should be placed at the beginning. */
99 struct _ceval_state ceval;
100
101 PyInterpreterState *next;
102
103 int64_t id;
104 int64_t id_refcount;
105 int requires_idref;
106 PyThread_type_lock id_mutex;
107
108 #define _PyInterpreterState_WHENCE_NOTSET -1
109 #define _PyInterpreterState_WHENCE_UNKNOWN 0
110 #define _PyInterpreterState_WHENCE_RUNTIME 1
111 #define _PyInterpreterState_WHENCE_LEGACY_CAPI 2
112 #define _PyInterpreterState_WHENCE_CAPI 3
113 #define _PyInterpreterState_WHENCE_XI 4
114 #define _PyInterpreterState_WHENCE_STDLIB 5
115 #define _PyInterpreterState_WHENCE_MAX 5
116 long _whence;
117
118 /* Has been initialized to a safe state.
119
120 In order to be effective, this must be set to 0 during or right
121 after allocation. */
122 int _initialized;
123 /* Has been fully initialized via pylifecycle.c. */
124 int _ready;
125 int finalizing;
126
127 uintptr_t last_restart_version;
128 struct pythreads {
129 uint64_t next_unique_id;
130 /* The linked list of threads, newest first. */
131 PyThreadState *head;
132 /* The thread currently executing in the __main__ module, if any. */
133 PyThreadState *main;
134 /* Used in Modules/_threadmodule.c. */
135 Py_ssize_t count;
136 /* Support for runtime thread stack size tuning.
137 A value of 0 means using the platform's default stack size
138 or the size specified by the THREAD_STACK_SIZE macro. */
139 /* Used in Python/thread.c. */
140 size_t stacksize;
141 } threads;
142
143 /* Reference to the _PyRuntime global variable. This field exists
144 to not have to pass runtime in addition to tstate to a function.
145 Get runtime from tstate: tstate->interp->runtime. */
146 struct pyruntimestate *runtime;
147
148 /* Set by Py_EndInterpreter().
149
150 Use _PyInterpreterState_GetFinalizing()
151 and _PyInterpreterState_SetFinalizing()
152 to access it, don't access it directly. */
153 PyThreadState* _finalizing;
154 /* The ID of the OS thread in which we are finalizing. */
155 unsigned long _finalizing_id;
156
157 struct _gc_runtime_state gc;
158
159 /* The following fields are here to avoid allocation during init.
160 The data is exposed through PyInterpreterState pointer fields.
161 These fields should not be accessed directly outside of init.
162
163 All other PyInterpreterState pointer fields are populated when
164 needed and default to NULL.
165
166 For now there are some exceptions to that rule, which require
167 allocation during init. These will be addressed on a case-by-case
168 basis. Also see _PyRuntimeState regarding the various mutex fields.
169 */
170
171 // Dictionary of the sys module
172 PyObject *sysdict;
173
174 // Dictionary of the builtins module
175 PyObject *builtins;
176
177 struct _import_state imports;
178
179 /* The per-interpreter GIL, which might not be used. */
180 struct _gil_runtime_state _gil;
181
182 /* ---------- IMPORTANT ---------------------------
183 The fields above this line are declared as early as
184 possible to facilitate out-of-process observability
185 tools. */
186
187 struct codecs_state codecs;
188
189 PyConfig config;
190 unsigned long feature_flags;
191
192 PyObject *dict; /* Stores per-interpreter state */
193
194 PyObject *sysdict_copy;
195 PyObject *builtins_copy;
196 // Initialized to _PyEval_EvalFrameDefault().
197 _PyFrameEvalFunction eval_frame;
198
199 PyFunction_WatchCallback func_watchers[FUNC_MAX_WATCHERS];
200 // One bit is set for each non-NULL entry in func_watchers
201 uint8_t active_func_watchers;
202
203 Py_ssize_t co_extra_user_count;
204 freefunc co_extra_freefuncs[MAX_CO_EXTRA_USERS];
205
206 /* cross-interpreter data and utils */
207 struct _xi_state xi;
208
209 #ifdef HAVE_FORK
210 PyObject *before_forkers;
211 PyObject *after_forkers_parent;
212 PyObject *after_forkers_child;
213 #endif
214
215 struct _warnings_runtime_state warnings;
216 struct atexit_state atexit;
217 struct _stoptheworld_state stoptheworld;
218 struct _qsbr_shared qsbr;
219
220 #if defined(Py_GIL_DISABLED)
221 struct _mimalloc_interp_state mimalloc;
222 struct _brc_state brc; // biased reference counting state
223 PyMutex weakref_locks[NUM_WEAKREF_LIST_LOCKS];
224 #endif
225
226 // Per-interpreter state for the obmalloc allocator. For the main
227 // interpreter and for all interpreters that don't have their
228 // own obmalloc state, this points to the static structure in
229 // obmalloc.c obmalloc_state_main. For other interpreters, it is
230 // heap allocated by _PyMem_init_obmalloc() and freed when the
231 // interpreter structure is freed. In the case of a heap allocated
232 // obmalloc state, it is not safe to hold on to or use memory after
233 // the interpreter is freed. The obmalloc state corresponding to
234 // that allocated memory is gone. See free_obmalloc_arenas() for
235 // more comments.
236 struct _obmalloc_state *obmalloc;
237
238 PyObject *audit_hooks;
239 PyType_WatchCallback type_watchers[TYPE_MAX_WATCHERS];
240 PyCode_WatchCallback code_watchers[CODE_MAX_WATCHERS];
241 // One bit is set for each non-NULL entry in code_watchers
242 uint8_t active_code_watchers;
243
244 struct _py_object_state object_state;
245 struct _Py_unicode_state unicode;
246 struct _Py_long_state long_state;
247 struct _dtoa_state dtoa;
248 struct _py_func_state func_state;
249 struct _py_code_state code_state;
250
251 struct _Py_dict_state dict_state;
252 struct _Py_exc_state exc_state;
253 struct _Py_mem_interp_free_queue mem_free_queue;
254
255 struct ast_state ast;
256 struct types_state types;
257 struct callable_cache callable_cache;
258 _PyOptimizerObject *optimizer;
259 _PyExecutorObject *executor_list_head;
260
261 _rare_events rare_events;
262 PyDict_WatchCallback builtins_dict_watcher;
263
264 _Py_GlobalMonitors monitors;
265 bool sys_profile_initialized;
266 bool sys_trace_initialized;
267 Py_ssize_t sys_profiling_threads; /* Count of threads with c_profilefunc set */
268 Py_ssize_t sys_tracing_threads; /* Count of threads with c_tracefunc set */
269 PyObject *monitoring_callables[PY_MONITORING_TOOL_IDS][_PY_MONITORING_EVENTS];
270 PyObject *monitoring_tool_names[PY_MONITORING_TOOL_IDS];
271
272 struct _Py_interp_cached_objects cached_objects;
273 struct _Py_interp_static_objects static_objects;
274
275 /* the initial PyInterpreterState.threads.head */
276 _PyThreadStateImpl _initial_thread;
277 Py_ssize_t _interactive_src_count;
278 // In 3.14+ this is interp->threads.preallocated.
279 _PyThreadStateImpl *threads_preallocated;
280 };
281
282
283 /* other API */
284
285 extern void _PyInterpreterState_Clear(PyThreadState *tstate);
286
287
288 static inline PyThreadState*
_PyInterpreterState_GetFinalizing(PyInterpreterState * interp)289 _PyInterpreterState_GetFinalizing(PyInterpreterState *interp) {
290 return (PyThreadState*)_Py_atomic_load_ptr_relaxed(&interp->_finalizing);
291 }
292
293 static inline unsigned long
_PyInterpreterState_GetFinalizingID(PyInterpreterState * interp)294 _PyInterpreterState_GetFinalizingID(PyInterpreterState *interp) {
295 return _Py_atomic_load_ulong_relaxed(&interp->_finalizing_id);
296 }
297
298 static inline void
_PyInterpreterState_SetFinalizing(PyInterpreterState * interp,PyThreadState * tstate)299 _PyInterpreterState_SetFinalizing(PyInterpreterState *interp, PyThreadState *tstate) {
300 _Py_atomic_store_ptr_relaxed(&interp->_finalizing, tstate);
301 if (tstate == NULL) {
302 _Py_atomic_store_ulong_relaxed(&interp->_finalizing_id, 0);
303 }
304 else {
305 // XXX Re-enable this assert once gh-109860 is fixed.
306 //assert(tstate->thread_id == PyThread_get_thread_ident());
307 _Py_atomic_store_ulong_relaxed(&interp->_finalizing_id,
308 tstate->thread_id);
309 }
310 }
311
312
313
314 // Exports for the _testinternalcapi module.
315 PyAPI_FUNC(int64_t) _PyInterpreterState_ObjectToID(PyObject *);
316 PyAPI_FUNC(PyInterpreterState *) _PyInterpreterState_LookUpID(int64_t);
317 PyAPI_FUNC(PyInterpreterState *) _PyInterpreterState_LookUpIDObject(PyObject *);
318 PyAPI_FUNC(int) _PyInterpreterState_IDInitref(PyInterpreterState *);
319 PyAPI_FUNC(int) _PyInterpreterState_IDIncref(PyInterpreterState *);
320 PyAPI_FUNC(void) _PyInterpreterState_IDDecref(PyInterpreterState *);
321
322 PyAPI_FUNC(int) _PyInterpreterState_IsReady(PyInterpreterState *interp);
323
324 PyAPI_FUNC(long) _PyInterpreterState_GetWhence(PyInterpreterState *interp);
325 extern void _PyInterpreterState_SetWhence(
326 PyInterpreterState *interp,
327 long whence);
328
329 extern const PyConfig* _PyInterpreterState_GetConfig(PyInterpreterState *interp);
330
331 // Get a copy of the current interpreter configuration.
332 //
333 // Return 0 on success. Raise an exception and return -1 on error.
334 //
335 // The caller must initialize 'config', using PyConfig_InitPythonConfig()
336 // for example.
337 //
338 // Python must be preinitialized to call this method.
339 // The caller must hold the GIL.
340 //
341 // Once done with the configuration, PyConfig_Clear() must be called to clear
342 // it.
343 //
344 // Export for '_testinternalcapi' shared extension.
345 PyAPI_FUNC(int) _PyInterpreterState_GetConfigCopy(
346 struct PyConfig *config);
347
348 // Set the configuration of the current interpreter.
349 //
350 // This function should be called during or just after the Python
351 // initialization.
352 //
353 // Update the sys module with the new configuration. If the sys module was
354 // modified directly after the Python initialization, these changes are lost.
355 //
356 // Some configuration like faulthandler or warnoptions can be updated in the
357 // configuration, but don't reconfigure Python (don't enable/disable
358 // faulthandler and don't reconfigure warnings filters).
359 //
360 // Return 0 on success. Raise an exception and return -1 on error.
361 //
362 // The configuration should come from _PyInterpreterState_GetConfigCopy().
363 //
364 // Export for '_testinternalcapi' shared extension.
365 PyAPI_FUNC(int) _PyInterpreterState_SetConfig(
366 const struct PyConfig *config);
367
368
369 /*
370 Runtime Feature Flags
371
372 Each flag indicate whether or not a specific runtime feature
373 is available in a given context. For example, forking the process
374 might not be allowed in the current interpreter (i.e. os.fork() would fail).
375 */
376
377 /* Set if the interpreter share obmalloc runtime state
378 with the main interpreter. */
379 #define Py_RTFLAGS_USE_MAIN_OBMALLOC (1UL << 5)
380
381 /* Set if import should check a module for subinterpreter support. */
382 #define Py_RTFLAGS_MULTI_INTERP_EXTENSIONS (1UL << 8)
383
384 /* Set if threads are allowed. */
385 #define Py_RTFLAGS_THREADS (1UL << 10)
386
387 /* Set if daemon threads are allowed. */
388 #define Py_RTFLAGS_DAEMON_THREADS (1UL << 11)
389
390 /* Set if os.fork() is allowed. */
391 #define Py_RTFLAGS_FORK (1UL << 15)
392
393 /* Set if os.exec*() is allowed. */
394 #define Py_RTFLAGS_EXEC (1UL << 16)
395
396 extern int _PyInterpreterState_HasFeature(PyInterpreterState *interp,
397 unsigned long feature);
398
399 PyAPI_FUNC(PyStatus) _PyInterpreterState_New(
400 PyThreadState *tstate,
401 PyInterpreterState **pinterp);
402
403
404 #define RARE_EVENT_INTERP_INC(interp, name) \
405 do { \
406 /* saturating add */ \
407 int val = FT_ATOMIC_LOAD_UINT8_RELAXED(interp->rare_events.name); \
408 if (val < UINT8_MAX) { \
409 FT_ATOMIC_STORE_UINT8(interp->rare_events.name, val + 1); \
410 } \
411 RARE_EVENT_STAT_INC(name); \
412 } while (0); \
413
414 #define RARE_EVENT_INC(name) \
415 do { \
416 PyInterpreterState *interp = PyInterpreterState_Get(); \
417 RARE_EVENT_INTERP_INC(interp, name); \
418 } while (0); \
419
420 #ifdef __cplusplus
421 }
422 #endif
423 #endif /* !Py_INTERNAL_INTERP_H */
424