Debian Codegraph @

Doc/c-api/threads.rst

raw
1 .. highlight:: c
2
3 .. _threads:
4
5 Thread states and the global interpreter lock
6 =============================================
7
8 .. index::
9 single: global interpreter lock
10 single: interpreter lock
11 single: lock, interpreter
12
13 Unless on a :term:`free-threaded build` of :term:`CPython`,
14 the Python interpreter is generally not thread-safe. In order to support
15 multi-threaded Python programs, there's a global lock, called the :term:`global
16 interpreter lock` or :term:`GIL`, that must be held by a thread before
17 accessing Python objects. Without the lock, even the simplest operations
18 could cause problems in a multi-threaded program: for example, when
19 two threads simultaneously increment the reference count of the same object, the
20 reference count could end up being incremented only once instead of twice.
21
22 As such, only a thread that holds the GIL may operate on Python objects or
23 invoke Python's C API.
24
25 .. index:: single: setswitchinterval (in module sys)
26
27 In order to emulate concurrency, the interpreter regularly tries to switch
28 threads between bytecode instructions (see :func:`sys.setswitchinterval`).
29 This is why locks are also necessary for thread-safety in pure-Python code.
30
31 Additionally, the global interpreter lock is released around blocking I/O
32 operations, such as reading or writing to a file. From the C API, this is done
33 by :ref:`detaching the thread state <detaching-thread-state>`.
34
35
36 .. index::
37 single: PyThreadState (C type)
38
39 The Python interpreter keeps some thread-local information inside
40 a data structure called :c:type:`PyThreadState`, known as a :term:`thread state`.
41 Each thread has a thread-local pointer to a :c:type:`PyThreadState`; a thread state
42 referenced by this pointer is considered to be :term:`attached <attached thread state>`.
43
44 A thread can only have one :term:`attached thread state` at a time. An attached
45 thread state is typically analogous with holding the GIL, except on
46 free-threaded builds. On builds with the GIL enabled, attaching a thread state
47 will block until the GIL can be acquired. However, even on builds with the GIL
48 disabled, it is still required to have an attached thread state, as the interpreter
49 needs to keep track of which threads may access Python objects.
50
51 .. note::
52
53 Even on the free-threaded build, attaching a thread state may block, as the
54 GIL can be re-enabled or threads might be temporarily suspended (such as during
55 a garbage collection).
56
57 Generally, there will always be an attached thread state when using Python's
58 C API, including during embedding and when implementing methods, so it's uncommon
59 to need to set up a thread state on your own. Only in some specific cases, such
60 as in a :c:macro:`Py_BEGIN_ALLOW_THREADS` block or in a fresh thread, will the
61 thread not have an attached thread state.
62 If uncertain, check if :c:func:`PyThreadState_GetUnchecked` returns ``NULL``.
63
64 If it turns out that you do need to create a thread state, call :c:func:`PyThreadState_New`
65 followed by :c:func:`PyThreadState_Swap`, or use the dangerous
66 :c:func:`PyGILState_Ensure` function.
67
68
69 .. _detaching-thread-state:
70
71 Detaching the thread state from extension code
72 ----------------------------------------------
73
74 Most extension code manipulating the :term:`thread state` has the following simple
75 structure::
76
77 Save the thread state in a local variable.
78 ... Do some blocking I/O operation ...
79 Restore the thread state from the local variable.
80
81 This is so common that a pair of macros exists to simplify it::
82
83 Py_BEGIN_ALLOW_THREADS
84 ... Do some blocking I/O operation ...
85 Py_END_ALLOW_THREADS
86
87 .. index::
88 single: Py_BEGIN_ALLOW_THREADS (C macro)
89 single: Py_END_ALLOW_THREADS (C macro)
90
91 The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
92 hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
93 block.
94
95 The block above expands to the following code::
96
97 PyThreadState *_save;
98
99 _save = PyEval_SaveThread();
100 ... Do some blocking I/O operation ...
101 PyEval_RestoreThread(_save);
102
103 .. index::
104 single: PyEval_RestoreThread (C function)
105 single: PyEval_SaveThread (C function)
106
107 Here is how these functions work:
108
109 The attached thread state implies that the GIL is held for the interpreter.
110 To detach it, :c:func:`PyEval_SaveThread` is called and the result is stored
111 in a local variable.
112
113 By detaching the thread state, the GIL is released, which allows other threads
114 to attach to the interpreter and execute while the current thread performs
115 blocking I/O. When the I/O operation is complete, the old thread state is
116 reattached by calling :c:func:`PyEval_RestoreThread`, which will wait until
117 the GIL can be acquired.
118
119 .. note::
120 Performing blocking I/O is the most common use case for detaching
121 the thread state, but it is also useful to call it over long-running
122 native code that doesn't need access to Python objects or Python's C API.
123 For example, the standard :mod:`zlib` and :mod:`hashlib` modules detach the
124 :term:`thread state <attached thread state>` when compressing or hashing
125 data.
126
127 On a :term:`free-threaded build`, the :term:`GIL` is usually out of the question,
128 but **detaching the thread state is still required**, because the interpreter
129 periodically needs to block all threads to get a consistent view of Python objects
130 without the risk of race conditions.
131 For example, CPython currently suspends all threads for a short period of time
132 while running the garbage collector.
133
134 .. warning::
135
136 Detaching the thread state can lead to unexpected behavior during interpreter
137 finalization. See :ref:`cautions-regarding-runtime-finalization` for more
138 details.
139
140
141 APIs
142 ^^^^
143
144 The following macros are normally used without a trailing semicolon; look for
145 example usage in the Python source distribution.
146
147 .. note::
148
149 These macros are still necessary on the :term:`free-threaded build` to prevent
150 deadlocks.
151
152 .. c:macro:: Py_BEGIN_ALLOW_THREADS
153
154 This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
155 Note that it contains an opening brace; it must be matched with a following
156 :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
157 macro.
158
159
160 .. c:macro:: Py_END_ALLOW_THREADS
161
162 This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
163 a closing brace; it must be matched with an earlier
164 :c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
165 this macro.
166
167
168 .. c:macro:: Py_BLOCK_THREADS
169
170 This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
171 :c:macro:`Py_END_ALLOW_THREADS` without the closing brace.
172
173
174 .. c:macro:: Py_UNBLOCK_THREADS
175
176 This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
177 :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
178 declaration.
179
180
181 Non-Python created threads
182 --------------------------
183
184 When threads are created using the dedicated Python APIs (such as the
185 :mod:`threading` module), a thread state is automatically associated with them,
186 However, when a thread is created from native code (for example, by a
187 third-party library with its own thread management), it doesn't hold an
188 attached thread state.
189
190 If you need to call Python code from these threads (often this will be part
191 of a callback API provided by the aforementioned third-party library),
192 you must first register these threads with the interpreter by
193 creating a new thread state and attaching it.
194
195 The most robust way to do this is through :c:func:`PyThreadState_New` followed
196 by :c:func:`PyThreadState_Swap`.
197
198 .. note::
199 ``PyThreadState_New`` requires an argument pointing to the desired
200 interpreter; such a pointer can be acquired via a call to
201 :c:func:`PyInterpreterState_Get` from the code where the thread was
202 created.
203
204 For example::
205
206 /* The return value of PyInterpreterState_Get() from the
207 function that created this thread. */
208 PyInterpreterState *interp = thread_data->interp;
209
210 /* Create a new thread state for the interpreter. It does not start out
211 attached. */
212 PyThreadState *tstate = PyThreadState_New(interp);
213
214 /* Attach the thread state, which will acquire the GIL. */
215 PyThreadState_Swap(tstate);
216
217 /* Perform Python actions here. */
218 result = CallSomeFunction();
219 /* evaluate result or handle exception */
220
221 /* Destroy the thread state. No Python API allowed beyond this point. */
222 PyThreadState_Clear(tstate);
223 PyThreadState_DeleteCurrent();
224
225 .. warning::
226
227 If the interpreter finalized before ``PyThreadState_Swap`` was called, then
228 ``interp`` will be a dangling pointer!
229
230 .. _gilstate:
231
232 Legacy API
233 ----------
234
235 Another common pattern to call Python code from a non-Python thread is to use
236 :c:func:`PyGILState_Ensure` followed by a call to :c:func:`PyGILState_Release`.
237
238 These functions do not work well when multiple interpreters exist in the Python
239 process. If no Python interpreter has ever been used in the current thread (which
240 is common for threads created outside Python), ``PyGILState_Ensure`` will create
241 and attach a thread state for the "main" interpreter (the first interpreter in
242 the Python process).
243
244 Additionally, these functions have thread-safety issues during interpreter
245 finalization. Using ``PyGILState_Ensure`` during finalization will likely
246 crash the process.
247
248 Usage of these functions look like such::
249
250 PyGILState_STATE gstate;
251 gstate = PyGILState_Ensure();
252
253 /* Perform Python actions here. */
254 result = CallSomeFunction();
255 /* evaluate result or handle exception */
256
257 /* Release the thread. No Python API allowed beyond this point. */
258 PyGILState_Release(gstate);
259
260
261 .. _fork-and-threads:
262
263 Cautions about fork()
264 ---------------------
265
266 Another important thing to note about threads is their behaviour in the face
267 of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a
268 process forks only the thread that issued the fork will exist. This has a
269 concrete impact both on how locks must be handled and on all stored state
270 in CPython's runtime.
271
272 The fact that only the "current" thread remains
273 means any locks held by other threads will never be released. Python solves
274 this for :func:`os.fork` by acquiring the locks it uses internally before
275 the fork, and releasing them afterwards. In addition, it resets any
276 :ref:`lock-objects` in the child. When extending or embedding Python, there
277 is no way to inform Python of additional (non-Python) locks that need to be
278 acquired before or reset after a fork. OS facilities such as
279 :c:func:`!pthread_atfork` would need to be used to accomplish the same thing.
280 Additionally, when extending or embedding Python, calling :c:func:`fork`
281 directly rather than through :func:`os.fork` (and returning to or calling
282 into Python) may result in a deadlock by one of Python's internal locks
283 being held by a thread that is defunct after the fork.
284 :c:func:`PyOS_AfterFork_Child` tries to reset the necessary locks, but is not
285 always able to.
286
287 The fact that all other threads go away also means that CPython's
288 runtime state there must be cleaned up properly, which :func:`os.fork`
289 does. This means finalizing all other :c:type:`PyThreadState` objects
290 belonging to the current interpreter and all other
291 :c:type:`PyInterpreterState` objects. Due to this and the special
292 nature of the :ref:`"main" interpreter <sub-interpreter-support>`,
293 :c:func:`fork` should only be called in that interpreter's "main"
294 thread, where the CPython global runtime was originally initialized.
295 The only exception is if :c:func:`exec` will be called immediately
296 after.
297
298
299 High-level APIs
300 ---------------
301
302 These are the most commonly used types and functions when writing multi-threaded
303 C extensions.
304
305
306 .. c:type:: PyThreadState
307
308 This data structure represents the state of a single thread. The only public
309 data member is:
310
311 .. c:member:: PyInterpreterState *interp
312
313 This thread's interpreter state.
314
315
316 .. c:function:: void PyEval_InitThreads()
317
318 .. index::
319 single: PyEval_AcquireThread()
320 single: PyEval_ReleaseThread()
321 single: PyEval_SaveThread()
322 single: PyEval_RestoreThread()
323
324 Deprecated function which does nothing.
325
326 In Python 3.6 and older, this function created the GIL if it didn't exist.
327
328 .. versionchanged:: 3.9
329 The function now does nothing.
330
331 .. versionchanged:: 3.7
332 This function is now called by :c:func:`Py_Initialize()`, so you don't
333 have to call it yourself anymore.
334
335 .. versionchanged:: 3.2
336 This function cannot be called before :c:func:`Py_Initialize()` anymore.
337
338 .. deprecated:: 3.9
339
340 .. index:: pair: module; _thread
341
342
343 .. c:function:: PyThreadState* PyEval_SaveThread()
344
345 Detach the :term:`attached thread state` and return it.
346 The thread will have no :term:`thread state` upon returning.
347
348
349 .. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)
350
351 Set the :term:`attached thread state` to *tstate*.
352 The passed :term:`thread state` **should not** be :term:`attached <attached thread state>`,
353 otherwise deadlock ensues. *tstate* will be attached upon returning.
354
355 .. note::
356 Calling this function from a thread when the runtime is finalizing will
357 hang the thread until the program exits, even if the thread was not
358 created by Python. Refer to
359 :ref:`cautions-regarding-runtime-finalization` for more details.
360
361 .. versionchanged:: 3.14
362 Hangs the current thread, rather than terminating it, if called while the
363 interpreter is finalizing.
364
365 .. c:function:: PyThreadState* PyThreadState_Get()
366
367 Return the :term:`attached thread state`. If the thread has no attached
368 thread state, (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS`
369 block), then this issues a fatal error (so that the caller needn't check
370 for ``NULL``).
371
372 See also :c:func:`PyThreadState_GetUnchecked`.
373
374 .. c:function:: PyThreadState* PyThreadState_GetUnchecked()
375
376 Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a
377 fatal error if it is NULL. The caller is responsible to check if the result
378 is NULL.
379
380 .. versionadded:: 3.13
381 In Python 3.5 to 3.12, the function was private and known as
382 ``_PyThreadState_UncheckedGet()``.
383
384
385 .. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
386
387 Set the :term:`attached thread state` to *tstate*, and return the
388 :term:`thread state` that was attached prior to calling.
389
390 This function is safe to call without an :term:`attached thread state`; it
391 will simply return ``NULL`` indicating that there was no prior thread state.
392
393 .. seealso::
394 :c:func:`PyEval_ReleaseThread`
395
396 .. note::
397 Similar to :c:func:`PyGILState_Ensure`, this function will hang the
398 thread if the runtime is finalizing.
399
400
401 GIL-state APIs
402 --------------
403
404 The following functions use thread-local storage, and are not compatible
405 with sub-interpreters:
406
407 .. c:type:: PyGILState_STATE
408
409 The type of the value returned by :c:func:`PyGILState_Ensure` and passed to
410 :c:func:`PyGILState_Release`.
411
412 .. c:enumerator:: PyGILState_LOCKED
413
414 The GIL was already held when :c:func:`PyGILState_Ensure` was called.
415
416 .. c:enumerator:: PyGILState_UNLOCKED
417
418 The GIL was not held when :c:func:`PyGILState_Ensure` was called.
419
420 .. c:function:: PyGILState_STATE PyGILState_Ensure()
421
422 Ensure that the current thread is ready to call the Python C API regardless
423 of the current state of Python, or of the :term:`attached thread state`. This may
424 be called as many times as desired by a thread as long as each call is
425 matched with a call to :c:func:`PyGILState_Release`. In general, other
426 thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
427 :c:func:`PyGILState_Release` calls as long as the thread state is restored to
428 its previous state before the Release(). For example, normal usage of the
429 :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is
430 acceptable.
431
432 The return value is an opaque "handle" to the :term:`attached thread state` when
433 :c:func:`PyGILState_Ensure` was called, and must be passed to
434 :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even
435 though recursive calls are allowed, these handles *cannot* be shared - each
436 unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
437 to :c:func:`PyGILState_Release`.
438
439 When the function returns, there will be an :term:`attached thread state`
440 and the thread will be able to call arbitrary Python code. Failure is a fatal error.
441
442 .. warning::
443 Calling this function when the runtime is finalizing is unsafe. Doing
444 so will either hang the thread until the program ends, or fully crash
445 the interpreter in rare cases. Refer to
446 :ref:`cautions-regarding-runtime-finalization` for more details.
447
448 .. versionchanged:: 3.14
449 Hangs the current thread, rather than terminating it, if called while the
450 interpreter is finalizing.
451
452 .. c:function:: void PyGILState_Release(PyGILState_STATE)
453
454 Release any resources previously acquired. After this call, Python's state will
455 be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call
456 (but generally this state will be unknown to the caller, hence the use of the
457 GILState API).
458
459 Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
460 :c:func:`PyGILState_Release` on the same thread.
461
462 .. c:function:: PyThreadState* PyGILState_GetThisThreadState()
463
464 Get the :term:`attached thread state` for this thread. May return ``NULL`` if no
465 GILState API has been used on the current thread. Note that the main thread
466 always has such a thread-state, even if no auto-thread-state call has been
467 made on the main thread. This is mainly a helper/diagnostic function.
468
469 .. note::
470 This function may return non-``NULL`` even when the :term:`thread state`
471 is detached.
472 Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked`
473 for most cases.
474
475 .. seealso:: :c:func:`PyThreadState_Get`
476
477 .. c:function:: int PyGILState_Check()
478
479 Return ``1`` if the current thread is holding the :term:`GIL` and ``0`` otherwise.
480 This function can be called from any thread at any time.
481 Only if it has had its :term:`thread state <attached thread state>` initialized
482 via :c:func:`PyGILState_Ensure` will it return ``1``.
483 This is mainly a helper/diagnostic function. It can be useful
484 for example in callback contexts or memory allocation functions when
485 knowing that the :term:`GIL` is locked can allow the caller to perform sensitive
486 actions or otherwise behave differently.
487
488 .. note::
489 If the current Python process has ever created a subinterpreter, this
490 function will *always* return ``1``. Prefer :c:func:`PyThreadState_GetUnchecked`
491 for most cases.
492
493 .. versionadded:: 3.4
494
495
496 Low-level APIs
497 --------------
498
499 .. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
500
501 Create a new thread state object belonging to the given interpreter object.
502 An :term:`attached thread state` is not needed.
503
504 .. c:function:: void PyThreadState_Clear(PyThreadState *tstate)
505
506 Reset all information in a :term:`thread state` object. *tstate*
507 must be :term:`attached <attached thread state>`
508
509 .. versionchanged:: 3.9
510 This function now calls the :c:member:`!PyThreadState.on_delete` callback.
511 Previously, that happened in :c:func:`PyThreadState_Delete`.
512
513 .. versionchanged:: 3.13
514 The :c:member:`!PyThreadState.on_delete` callback was removed.
515
516
517 .. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
518
519 Destroy a :term:`thread state` object. *tstate* should not
520 be :term:`attached <attached thread state>` to any thread.
521 *tstate* must have been reset with a previous call to
522 :c:func:`PyThreadState_Clear`.
523
524
525 .. c:function:: void PyThreadState_DeleteCurrent(void)
526
527 Detach the :term:`attached thread state` (which must have been reset
528 with a previous call to :c:func:`PyThreadState_Clear`) and then destroy it.
529
530 No :term:`thread state` will be :term:`attached <attached thread state>` upon
531 returning.
532
533 .. c:function:: PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
534
535 Get the current frame of the Python thread state *tstate*.
536
537 Return a :term:`strong reference`. Return ``NULL`` if no frame is currently
538 executing.
539
540 See also :c:func:`PyEval_GetFrame`.
541
542 *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
543
544 .. versionadded:: 3.9
545
546
547 .. c:function:: uint64_t PyThreadState_GetID(PyThreadState *tstate)
548
549 Get the unique :term:`thread state` identifier of the Python thread state *tstate*.
550
551 *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
552
553 .. versionadded:: 3.9
554
555
556 .. c:function:: PyInterpreterState* PyThreadState_GetInterpreter(PyThreadState *tstate)
557
558 Get the interpreter of the Python thread state *tstate*.
559
560 *tstate* must not be ``NULL``, and must be :term:`attached <attached thread state>`.
561
562 .. versionadded:: 3.9
563
564
565 .. c:function:: void PyThreadState_EnterTracing(PyThreadState *tstate)
566
567 Suspend tracing and profiling in the Python thread state *tstate*.
568
569 Resume them using the :c:func:`PyThreadState_LeaveTracing` function.
570
571 .. versionadded:: 3.11
572
573
574 .. c:function:: void PyThreadState_LeaveTracing(PyThreadState *tstate)
575
576 Resume tracing and profiling in the Python thread state *tstate* suspended
577 by the :c:func:`PyThreadState_EnterTracing` function.
578
579 See also :c:func:`PyEval_SetTrace` and :c:func:`PyEval_SetProfile`
580 functions.
581
582 .. versionadded:: 3.11
583
584
585 .. c:function:: int PyUnstable_ThreadState_SetStackProtection(PyThreadState *tstate, void *stack_start_addr, size_t stack_size)
586
587 Set the stack protection start address and stack protection size
588 of a Python thread state.
589
590 On success, return ``0``.
591 On failure, set an exception and return ``-1``.
592
593 CPython implements :ref:`recursion control <recursion>` for C code by raising
594 :py:exc:`RecursionError` when it notices that the machine execution stack is close
595 to overflow. See for example the :c:func:`Py_EnterRecursiveCall` function.
596 For this, it needs to know the location of the current thread's stack, which it
597 normally gets from the operating system.
598 When the stack is changed, for example using context switching techniques like the
599 Boost library's ``boost::context``, you must call
600 :c:func:`~PyUnstable_ThreadState_SetStackProtection` to inform CPython of the change.
601
602 Call :c:func:`~PyUnstable_ThreadState_SetStackProtection` either before
603 or after changing the stack.
604 Do not call any other Python C API between the call and the stack
605 change.
606
607 See :c:func:`PyUnstable_ThreadState_ResetStackProtection` for undoing this operation.
608
609 .. versionadded:: 3.15
610
611
612 .. c:function:: void PyUnstable_ThreadState_ResetStackProtection(PyThreadState *tstate)
613
614 Reset the stack protection start address and stack protection size
615 of a Python thread state to the operating system defaults.
616
617 See :c:func:`PyUnstable_ThreadState_SetStackProtection` for an explanation.
618
619 .. versionadded:: 3.15
620
621
622 .. c:function:: PyObject* PyThreadState_GetDict()
623
624 Return a dictionary in which extensions can store thread-specific state
625 information. Each extension should use a unique key to use to store state in
626 the dictionary. It is okay to call this function when no :term:`thread state`
627 is :term:`attached <attached thread state>`. If this function returns
628 ``NULL``, no exception has been raised and the caller should assume no
629 thread state is attached.
630
631
632 .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
633
634 :term:`Attach <attached thread state>` *tstate* to the current thread,
635 which must not be ``NULL`` or already :term:`attached <attached thread state>`.
636
637 The calling thread must not already have an :term:`attached thread state`.
638
639 .. note::
640 Calling this function from a thread when the runtime is finalizing will
641 hang the thread until the program exits, even if the thread was not
642 created by Python. Refer to
643 :ref:`cautions-regarding-runtime-finalization` for more details.
644
645 .. versionchanged:: 3.8
646 Updated to be consistent with :c:func:`PyEval_RestoreThread`,
647 :c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`,
648 and terminate the current thread if called while the interpreter is finalizing.
649
650 .. versionchanged:: 3.14
651 Hangs the current thread, rather than terminating it, if called while the
652 interpreter is finalizing.
653
654 :c:func:`PyEval_RestoreThread` is a higher-level function which is always
655 available (even when threads have not been initialized).
656
657
658 .. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
659
660 Detach the :term:`attached thread state`.
661 The *tstate* argument, which must not be ``NULL``, is only used to check
662 that it represents the :term:`attached thread state` --- if it isn't, a fatal error is
663 reported.
664
665 :c:func:`PyEval_SaveThread` is a higher-level function which is always
666 available (even when threads have not been initialized).
667
668
669 Asynchronous notifications
670 ==========================
671
672 A mechanism is provided to make asynchronous notifications to the main
673 interpreter thread. These notifications take the form of a function
674 pointer and a void pointer argument.
675
676
677 .. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)
678
679 Schedule a function to be called from the main interpreter thread. On
680 success, ``0`` is returned and *func* is queued for being called in the
681 main thread. On failure, ``-1`` is returned without setting any exception.
682
683 When successfully queued, *func* will be *eventually* called from the
684 main interpreter thread with the argument *arg*. It will be called
685 asynchronously with respect to normally running Python code, but with
686 both these conditions met:
687
688 * on a :term:`bytecode` boundary;
689 * with the main thread holding an :term:`attached thread state`
690 (*func* can therefore use the full C API).
691
692 *func* must return ``0`` on success, or ``-1`` on failure with an exception
693 set. *func* won't be interrupted to perform another asynchronous
694 notification recursively, but it can still be interrupted to switch
695 threads if the :term:`thread state <attached thread state>` is detached.
696
697 This function doesn't need an :term:`attached thread state`. However, to call this
698 function in a subinterpreter, the caller must have an :term:`attached thread state`.
699 Otherwise, the function *func* can be scheduled to be called from the wrong interpreter.
700
701 .. warning::
702 This is a low-level function, only useful for very special cases.
703 There is no guarantee that *func* will be called as quick as
704 possible. If the main thread is busy executing a system call,
705 *func* won't be called before the system call returns. This
706 function is generally **not** suitable for calling Python code from
707 arbitrary C threads. Instead, use the :ref:`PyGILState API<gilstate>`.
708
709 .. versionadded:: 3.1
710
711 .. versionchanged:: 3.9
712 If this function is called in a subinterpreter, the function *func* is
713 now scheduled to be called from the subinterpreter, rather than being
714 called from the main interpreter. Each subinterpreter now has its own
715 list of scheduled calls.
716
717 .. versionchanged:: 3.12
718 This function now always schedules *func* to be run in the main
719 interpreter.
720
721
722 .. c:function:: int Py_MakePendingCalls(void)
723
724 Execute all pending calls. This is usually executed automatically by the
725 interpreter.
726
727 This function returns ``0`` on success, and returns ``-1`` with an exception
728 set on failure.
729
730 If this is not called in the main thread of the main
731 interpreter, this function does nothing and returns ``0``.
732 The caller must hold an :term:`attached thread state`.
733
734 .. versionadded:: 3.1
735
736 .. versionchanged:: 3.12
737 This function only runs pending calls in the main interpreter.
738
739
740 .. c:function:: int PyThreadState_SetAsyncExc(unsigned long id, PyObject *exc)
741
742 Asynchronously raise an exception in a thread. The *id* argument is the thread
743 id of the target thread; *exc* is the exception object to be raised. This
744 function does not steal any references to *exc*. To prevent naive misuse, you
745 must write your own C extension to call this. Must be called with an :term:`attached thread state`.
746 Returns the number of thread states modified; this is normally one, but will be
747 zero if the thread id isn't found. If *exc* is ``NULL``, the pending
748 exception (if any) for the thread is cleared. This raises no exceptions.
749
750 .. versionchanged:: 3.7
751 The type of the *id* parameter changed from :c:expr:`long` to
752 :c:expr:`unsigned long`.
753
754
755 Operating system thread APIs
756 ============================
757
758 .. c:macro:: PYTHREAD_INVALID_THREAD_ID
759
760 Sentinel value for an invalid thread ID.
761
762 This is currently equivalent to ``(unsigned long)-1``.
763
764
765 .. c:function:: unsigned long PyThread_start_new_thread(void (*func)(void *), void *arg)
766
767 Start function *func* in a new thread with argument *arg*.
768 The resulting thread is not intended to be joined.
769
770 *func* must not be ``NULL``, but *arg* may be ``NULL``.
771
772 On success, this function returns the identifier of the new thread; on failure,
773 this returns :c:macro:`PYTHREAD_INVALID_THREAD_ID`.
774
775 The caller does not need to hold an :term:`attached thread state`.
776
777
778 .. c:function:: unsigned long PyThread_get_thread_ident(void)
779
780 Return the identifier of the current thread, which will never be zero.
781
782 This function cannot fail, and the caller does not need to hold an
783 :term:`attached thread state`.
784
785 .. seealso::
786 :py:func:`threading.get_ident`
787
788
789 .. c:function:: PyObject *PyThread_GetInfo(void)
790
791 Get general information about the current thread in the form of a
792 :ref:`struct sequence <struct-sequence-objects>` object. This information is
793 accessible as :py:attr:`sys.thread_info` in Python.
794
795 On success, this returns a new :term:`strong reference` to the thread
796 information; on failure, this returns ``NULL`` with an exception set.
797
798 The caller must hold an :term:`attached thread state`.
799
800
801 .. c:macro:: PY_HAVE_THREAD_NATIVE_ID
802
803 This macro is defined when the system supports native thread IDs.
804
805
806 .. c:function:: unsigned long PyThread_get_thread_native_id(void)
807
808 Get the native identifier of the current thread as it was assigned by the operating
809 system's kernel, which will never be less than zero.
810
811 This function is only available when :c:macro:`PY_HAVE_THREAD_NATIVE_ID` is
812 defined.
813
814 This function cannot fail, and the caller does not need to hold an
815 :term:`attached thread state`.
816
817 .. seealso::
818 :py:func:`threading.get_native_id`
819
820
821 .. c:function:: void PyThread_exit_thread(void)
822
823 Terminate the current thread. This function is generally considered unsafe
824 and should be avoided. It is kept solely for backwards compatibility.
825
826 This function is only safe to call if all functions in the full call
827 stack are written to safely allow it.
828
829 .. warning::
830
831 If the current system uses POSIX threads (also known as "pthreads"),
832 this calls :manpage:`pthread_exit(3)`, which attempts to unwind the stack
833 and call C++ destructors on some libc implementations. However, if a
834 ``noexcept`` function is reached, it may terminate the process.
835 Other systems, such as macOS, do unwinding.
836
837 On Windows, this function calls ``_endthreadex()``, which kills the thread
838 without calling C++ destructors.
839
840 In any case, there is a risk of corruption on the thread's stack.
841
842 .. deprecated:: 3.14
843
844
845 .. c:function:: void PyThread_init_thread(void)
846
847 Initialize ``PyThread*`` APIs. Python executes this function automatically,
848 so there's little need to call it from an extension module.
849
850
851 .. c:function:: int PyThread_set_stacksize(size_t size)
852
853 Set the stack size of the current thread to *size* bytes.
854
855 This function returns ``0`` on success, ``-1`` if *size* is invalid, or
856 ``-2`` if the system does not support changing the stack size. This function
857 does not set exceptions.
858
859 The caller does not need to hold an :term:`attached thread state`.
860
861
862 .. c:function:: size_t PyThread_get_stacksize(void)
863
864 Return the stack size of the current thread in bytes, or ``0`` if the system's
865 default stack size is in use.
866
867 The caller does not need to hold an :term:`attached thread state`.