Debian Codegraph @

Include/internal/pycore_crossinterp.h

raw
1 #ifndef Py_INTERNAL_CROSSINTERP_H
2 #define Py_INTERNAL_CROSSINTERP_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 "pycore_pyerrors.h"
12
13
14 /**************/
15 /* exceptions */
16 /**************/
17
18 PyAPI_DATA(PyObject *) PyExc_InterpreterError;
19 PyAPI_DATA(PyObject *) PyExc_InterpreterNotFoundError;
20
21
22 /***************************/
23 /* cross-interpreter calls */
24 /***************************/
25
26 typedef int (*_Py_simple_func)(void *);
27 extern int _Py_CallInInterpreter(
28 PyInterpreterState *interp,
29 _Py_simple_func func,
30 void *arg);
31 extern int _Py_CallInInterpreterAndRawFree(
32 PyInterpreterState *interp,
33 _Py_simple_func func,
34 void *arg);
35
36
37 /**************************/
38 /* cross-interpreter data */
39 /**************************/
40
41 typedef struct _xidata _PyXIData_t;
42 typedef PyObject *(*xid_newobjfunc)(_PyXIData_t *);
43 typedef void (*xid_freefunc)(void *);
44
45 // _PyXIData_t is similar to Py_buffer as an effectively
46 // opaque struct that holds data outside the object machinery. This
47 // is necessary to pass safely between interpreters in the same process.
48 struct _xidata {
49 // data is the cross-interpreter-safe derivation of a Python object
50 // (see _PyObject_GetXIData). It will be NULL if the
51 // new_object func (below) encodes the data.
52 void *data;
53 // obj is the Python object from which the data was derived. This
54 // is non-NULL only if the data remains bound to the object in some
55 // way, such that the object must be "released" (via a decref) when
56 // the data is released. In that case the code that sets the field,
57 // likely a registered "xidatafunc", is responsible for
58 // ensuring it owns the reference (i.e. incref).
59 PyObject *obj;
60 // interpid is the ID of the owning interpreter of the original
61 // object. It corresponds to the active interpreter when
62 // _PyObject_GetXIData() was called. This should only
63 // be set by the cross-interpreter machinery.
64 //
65 // We use the ID rather than the PyInterpreterState to avoid issues
66 // with deleted interpreters. Note that IDs are never re-used, so
67 // each one will always correspond to a specific interpreter
68 // (whether still alive or not).
69 int64_t interpid;
70 // new_object is a function that returns a new object in the current
71 // interpreter given the data. The resulting object (a new
72 // reference) will be equivalent to the original object. This field
73 // is required.
74 xid_newobjfunc new_object;
75 // free is called when the data is released. If it is NULL then
76 // nothing will be done to free the data. For some types this is
77 // okay (e.g. bytes) and for those types this field should be set
78 // to NULL. However, for most the data was allocated just for
79 // cross-interpreter use, so it must be freed when
80 // _PyXIData_Release is called or the memory will
81 // leak. In that case, at the very least this field should be set
82 // to PyMem_RawFree (the default if not explicitly set to NULL).
83 // The call will happen with the original interpreter activated.
84 xid_freefunc free;
85 };
86
87 PyAPI_FUNC(_PyXIData_t *) _PyXIData_New(void);
88 PyAPI_FUNC(void) _PyXIData_Free(_PyXIData_t *data);
89
90 #define _PyXIData_DATA(DATA) ((DATA)->data)
91 #define _PyXIData_OBJ(DATA) ((DATA)->obj)
92 #define _PyXIData_INTERPID(DATA) ((DATA)->interpid)
93 // Users should not need getters for "new_object" or "free".
94
95
96 /* defining cross-interpreter data */
97
98 PyAPI_FUNC(void) _PyXIData_Init(
99 _PyXIData_t *data,
100 PyInterpreterState *interp, void *shared, PyObject *obj,
101 xid_newobjfunc new_object);
102 PyAPI_FUNC(int) _PyXIData_InitWithSize(
103 _PyXIData_t *,
104 PyInterpreterState *interp, const size_t, PyObject *,
105 xid_newobjfunc);
106 PyAPI_FUNC(void) _PyXIData_Clear(PyInterpreterState *, _PyXIData_t *);
107
108 // Normally the Init* functions are sufficient. The only time
109 // additional initialization might be needed is to set the "free" func,
110 // though that should be infrequent.
111 #define _PyXIData_SET_FREE(DATA, FUNC) \
112 do { \
113 (DATA)->free = (FUNC); \
114 } while (0)
115 #define _PyXIData_CHECK_FREE(DATA, FUNC) \
116 ((DATA)->free == (FUNC))
117 // Additionally, some shareable types are essentially light wrappers
118 // around other shareable types. The xidatafunc of the wrapper
119 // can often be implemented by calling the wrapped object's
120 // xidatafunc and then changing the "new_object" function.
121 // We have _PyXIData_SET_NEW_OBJECT() here for that,
122 // but might be better to have a function like
123 // _PyXIData_AdaptToWrapper() instead.
124 #define _PyXIData_SET_NEW_OBJECT(DATA, FUNC) \
125 do { \
126 (DATA)->new_object = (FUNC); \
127 } while (0)
128 #define _PyXIData_CHECK_NEW_OBJECT(DATA, FUNC) \
129 ((DATA)->new_object == (FUNC))
130
131
132 /* getting cross-interpreter data */
133
134 typedef int xidata_fallback_t;
135 #define _PyXIDATA_XIDATA_ONLY (0)
136 #define _PyXIDATA_FULL_FALLBACK (1)
137
138 // Technically, we don't need two different function types;
139 // we could go with just the fallback one. However, only container
140 // types like tuple need it, so always having the extra arg would be
141 // a bit unfortunate. It's also nice to be able to clearly distinguish
142 // between types that might call _PyObject_GetXIData() and those that won't.
143 //
144 typedef int (*xidatafunc)(PyThreadState *, PyObject *, _PyXIData_t *);
145 typedef int (*xidatafbfunc)(
146 PyThreadState *, PyObject *, xidata_fallback_t, _PyXIData_t *);
147 typedef struct {
148 xidatafunc basic;
149 xidatafbfunc fallback;
150 } _PyXIData_getdata_t;
151
152 PyAPI_FUNC(PyObject *) _PyXIData_GetNotShareableErrorType(PyThreadState *);
153 PyAPI_FUNC(void) _PyXIData_SetNotShareableError(PyThreadState *, const char *);
154 PyAPI_FUNC(void) _PyXIData_FormatNotShareableError(
155 PyThreadState *,
156 const char *,
157 ...);
158
159 PyAPI_FUNC(_PyXIData_getdata_t) _PyXIData_Lookup(
160 PyThreadState *,
161 PyObject *);
162 PyAPI_FUNC(int) _PyObject_CheckXIData(
163 PyThreadState *,
164 PyObject *);
165
166 PyAPI_FUNC(int) _PyObject_GetXIDataNoFallback(
167 PyThreadState *,
168 PyObject *,
169 _PyXIData_t *);
170 PyAPI_FUNC(int) _PyObject_GetXIData(
171 PyThreadState *,
172 PyObject *,
173 xidata_fallback_t,
174 _PyXIData_t *);
175
176 // _PyObject_GetXIData() for bytes
177 typedef struct {
178 const char *bytes;
179 Py_ssize_t len;
180 } _PyBytes_data_t;
181 PyAPI_FUNC(int) _PyBytes_GetData(PyObject *, _PyBytes_data_t *);
182 PyAPI_FUNC(PyObject *) _PyBytes_FromData(_PyBytes_data_t *);
183 PyAPI_FUNC(PyObject *) _PyBytes_FromXIData(_PyXIData_t *);
184 PyAPI_FUNC(int) _PyBytes_GetXIData(
185 PyThreadState *,
186 PyObject *,
187 _PyXIData_t *);
188 PyAPI_FUNC(_PyBytes_data_t *) _PyBytes_GetXIDataWrapped(
189 PyThreadState *,
190 PyObject *,
191 size_t,
192 xid_newobjfunc,
193 _PyXIData_t *);
194
195 // _PyObject_GetXIData() for pickle
196 PyAPI_DATA(PyObject *) _PyPickle_LoadFromXIData(_PyXIData_t *);
197 PyAPI_FUNC(int) _PyPickle_GetXIData(
198 PyThreadState *,
199 PyObject *,
200 _PyXIData_t *);
201
202 // _PyObject_GetXIData() for marshal
203 PyAPI_FUNC(PyObject *) _PyMarshal_ReadObjectFromXIData(_PyXIData_t *);
204 PyAPI_FUNC(int) _PyMarshal_GetXIData(
205 PyThreadState *,
206 PyObject *,
207 _PyXIData_t *);
208
209 // _PyObject_GetXIData() for code objects
210 PyAPI_FUNC(PyObject *) _PyCode_FromXIData(_PyXIData_t *);
211 PyAPI_FUNC(int) _PyCode_GetXIData(
212 PyThreadState *,
213 PyObject *,
214 _PyXIData_t *);
215 PyAPI_FUNC(int) _PyCode_GetScriptXIData(
216 PyThreadState *,
217 PyObject *,
218 _PyXIData_t *);
219 PyAPI_FUNC(int) _PyCode_GetPureScriptXIData(
220 PyThreadState *,
221 PyObject *,
222 _PyXIData_t *);
223
224 // _PyObject_GetXIData() for functions
225 PyAPI_FUNC(PyObject *) _PyFunction_FromXIData(_PyXIData_t *);
226 PyAPI_FUNC(int) _PyFunction_GetXIData(
227 PyThreadState *,
228 PyObject *,
229 _PyXIData_t *);
230
231
232 /* using cross-interpreter data */
233
234 PyAPI_FUNC(PyObject *) _PyXIData_NewObject(_PyXIData_t *);
235 PyAPI_FUNC(int) _PyXIData_Release(_PyXIData_t *);
236 PyAPI_FUNC(int) _PyXIData_ReleaseAndRawFree(_PyXIData_t *);
237
238
239 /* cross-interpreter data registry */
240
241 #define Py_CORE_CROSSINTERP_DATA_REGISTRY_H
242 #include "pycore_crossinterp_data_registry.h"
243 #undef Py_CORE_CROSSINTERP_DATA_REGISTRY_H
244
245
246 /*****************************/
247 /* runtime state & lifecycle */
248 /*****************************/
249
250 typedef struct _xid_lookup_state _PyXIData_lookup_t;
251
252 typedef struct {
253 // builtin types
254 _PyXIData_lookup_t data_lookup;
255 } _PyXI_global_state_t;
256
257 typedef struct {
258 // heap types
259 _PyXIData_lookup_t data_lookup;
260
261 struct xi_exceptions {
262 // static types
263 PyObject *PyExc_InterpreterError;
264 PyObject *PyExc_InterpreterNotFoundError;
265 // heap types
266 PyObject *PyExc_NotShareableError;
267 } exceptions;
268 } _PyXI_state_t;
269
270 #define _PyXI_GET_GLOBAL_STATE(interp) (&(interp)->runtime->xi)
271 #define _PyXI_GET_STATE(interp) (&(interp)->xi)
272
273 #ifndef Py_BUILD_CORE_MODULE
274 extern PyStatus _PyXI_Init(PyInterpreterState *interp);
275 extern void _PyXI_Fini(PyInterpreterState *interp);
276 extern PyStatus _PyXI_InitTypes(PyInterpreterState *interp);
277 extern void _PyXI_FiniTypes(PyInterpreterState *interp);
278 #endif // Py_BUILD_CORE_MODULE
279
280 int _Py_xi_global_state_init(_PyXI_global_state_t *);
281 void _Py_xi_global_state_fini(_PyXI_global_state_t *);
282 int _Py_xi_state_init(_PyXI_state_t *, PyInterpreterState *);
283 void _Py_xi_state_fini(_PyXI_state_t *, PyInterpreterState *);
284
285
286 /***************************/
287 /* short-term data sharing */
288 /***************************/
289
290 // Ultimately we'd like to preserve enough information about the
291 // exception and traceback that we could re-constitute (or at least
292 // simulate, a la traceback.TracebackException), and even chain, a copy
293 // of the exception in the calling interpreter.
294
295 typedef struct _excinfo {
296 struct _excinfo_type {
297 PyTypeObject *builtin;
298 const char *name;
299 const char *qualname;
300 const char *module;
301 } type;
302 const char *msg;
303 const char *errdisplay;
304 } _PyXI_excinfo;
305
306 PyAPI_FUNC(_PyXI_excinfo *) _PyXI_NewExcInfo(PyObject *exc);
307 PyAPI_FUNC(void) _PyXI_FreeExcInfo(_PyXI_excinfo *info);
308 PyAPI_FUNC(PyObject *) _PyXI_FormatExcInfo(_PyXI_excinfo *info);
309 PyAPI_FUNC(PyObject *) _PyXI_ExcInfoAsObject(_PyXI_excinfo *info);
310
311
312 typedef enum error_code {
313 _PyXI_ERR_NO_ERROR = 0,
314 _PyXI_ERR_UNCAUGHT_EXCEPTION = -1,
315 _PyXI_ERR_OTHER = -2,
316 _PyXI_ERR_NO_MEMORY = -3,
317 _PyXI_ERR_ALREADY_RUNNING = -4,
318 _PyXI_ERR_MAIN_NS_FAILURE = -5,
319 _PyXI_ERR_APPLY_NS_FAILURE = -6,
320 _PyXI_ERR_PRESERVE_FAILURE = -7,
321 _PyXI_ERR_EXC_PROPAGATION_FAILURE = -8,
322 _PyXI_ERR_NOT_SHAREABLE = -9,
323 } _PyXI_errcode;
324
325 typedef struct xi_failure _PyXI_failure;
326
327 PyAPI_FUNC(_PyXI_failure *) _PyXI_NewFailure(void);
328 PyAPI_FUNC(void) _PyXI_FreeFailure(_PyXI_failure *);
329 PyAPI_FUNC(_PyXI_errcode) _PyXI_GetFailureCode(_PyXI_failure *);
330 PyAPI_FUNC(int) _PyXI_InitFailure(_PyXI_failure *, _PyXI_errcode, PyObject *);
331 PyAPI_FUNC(void) _PyXI_InitFailureUTF8(
332 _PyXI_failure *,
333 _PyXI_errcode,
334 const char *);
335
336 PyAPI_FUNC(int) _PyXI_UnwrapNotShareableError(
337 PyThreadState *,
338 _PyXI_failure *);
339
340
341 // A cross-interpreter session involves entering an interpreter
342 // with _PyXI_Enter(), doing some work with it, and finally exiting
343 // that interpreter with _PyXI_Exit().
344 //
345 // At the boundaries of the session, both entering and exiting,
346 // data may be exchanged between the previous interpreter and the
347 // target one in a thread-safe way that does not violate the
348 // isolation between interpreters. This includes setting objects
349 // in the target's __main__ module on the way in, and capturing
350 // uncaught exceptions on the way out.
351 typedef struct xi_session _PyXI_session;
352
353 PyAPI_FUNC(_PyXI_session *) _PyXI_NewSession(void);
354 PyAPI_FUNC(void) _PyXI_FreeSession(_PyXI_session *);
355
356 typedef struct {
357 PyObject *preserved;
358 PyObject *excinfo;
359 _PyXI_errcode errcode;
360 } _PyXI_session_result;
361 PyAPI_FUNC(void) _PyXI_ClearResult(_PyXI_session_result *);
362
363 PyAPI_FUNC(int) _PyXI_Enter(
364 _PyXI_session *session,
365 PyInterpreterState *interp,
366 PyObject *nsupdates,
367 _PyXI_session_result *);
368 PyAPI_FUNC(int) _PyXI_Exit(
369 _PyXI_session *,
370 _PyXI_failure *,
371 _PyXI_session_result *);
372
373 PyAPI_FUNC(PyObject *) _PyXI_GetMainNamespace(
374 _PyXI_session *,
375 _PyXI_failure *);
376
377 PyAPI_FUNC(int) _PyXI_Preserve(
378 _PyXI_session *,
379 const char *,
380 PyObject *,
381 _PyXI_failure *);
382 PyAPI_FUNC(PyObject *) _PyXI_GetPreserved(
383 _PyXI_session_result *,
384 const char *);
385
386
387 /*************/
388 /* other API */
389 /*************/
390
391 // Export for _testinternalcapi shared extension
392 PyAPI_FUNC(PyInterpreterState *) _PyXI_NewInterpreter(
393 PyInterpreterConfig *config,
394 long *maybe_whence,
395 PyThreadState **p_tstate,
396 PyThreadState **p_save_tstate);
397 PyAPI_FUNC(void) _PyXI_EndInterpreter(
398 PyInterpreterState *interp,
399 PyThreadState *tstate,
400 PyThreadState **p_save_tstate);
401
402
403 #ifdef __cplusplus
404 }
405 #endif
406 #endif /* !Py_INTERNAL_CROSSINTERP_H */