| 1 |
:mod:`!_thread` --- Low-level threading API |
| 2 |
=========================================== |
| 3 |
|
| 4 |
.. module:: _thread |
| 5 |
:synopsis: Low-level threading API. |
| 6 |
|
| 7 |
.. index:: |
| 8 |
single: light-weight processes |
| 9 |
single: processes, light-weight |
| 10 |
single: binary semaphores |
| 11 |
single: semaphores, binary |
| 12 |
|
| 13 |
-------------- |
| 14 |
|
| 15 |
This module provides low-level primitives for working with multiple threads |
| 16 |
(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of |
| 17 |
control sharing their global data space. For synchronization, simple locks |
| 18 |
(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided. |
| 19 |
The :mod:`threading` module provides an easier to use and higher-level |
| 20 |
threading API built on top of this module. |
| 21 |
|
| 22 |
.. index:: |
| 23 |
single: pthreads |
| 24 |
pair: threads; POSIX |
| 25 |
|
| 26 |
.. versionchanged:: 3.7 |
| 27 |
This module used to be optional, it is now always available. |
| 28 |
|
| 29 |
This module defines the following constants and functions: |
| 30 |
|
| 31 |
.. exception:: error |
| 32 |
|
| 33 |
Raised on thread-specific errors. |
| 34 |
|
| 35 |
.. versionchanged:: 3.3 |
| 36 |
This is now a synonym of the built-in :exc:`RuntimeError`. |
| 37 |
|
| 38 |
|
| 39 |
.. data:: LockType |
| 40 |
|
| 41 |
This is the type of lock objects. |
| 42 |
|
| 43 |
|
| 44 |
.. function:: start_new_thread(function, args[, kwargs]) |
| 45 |
|
| 46 |
Start a new thread and return its identifier. The thread executes the |
| 47 |
function *function* with the argument list *args* (which must be a tuple). |
| 48 |
The optional *kwargs* argument specifies a dictionary of keyword arguments. |
| 49 |
|
| 50 |
When the function returns, the thread silently exits. |
| 51 |
|
| 52 |
When the function terminates with an unhandled exception, |
| 53 |
:func:`sys.unraisablehook` is called to handle the exception. The *object* |
| 54 |
attribute of the hook argument is *function*. By default, a stack trace is |
| 55 |
printed and then the thread exits (but other threads continue to run). |
| 56 |
|
| 57 |
When the function raises a :exc:`SystemExit` exception, it is silently |
| 58 |
ignored. |
| 59 |
|
| 60 |
.. audit-event:: _thread.start_new_thread function,args,kwargs start_new_thread |
| 61 |
|
| 62 |
.. versionchanged:: 3.8 |
| 63 |
:func:`sys.unraisablehook` is now used to handle unhandled exceptions. |
| 64 |
|
| 65 |
|
| 66 |
.. function:: interrupt_main(signum=signal.SIGINT, /) |
| 67 |
|
| 68 |
Simulate the effect of a signal arriving in the main thread. |
| 69 |
A thread can use this function to interrupt the main thread, though |
| 70 |
there is no guarantee that the interruption will happen immediately. |
| 71 |
|
| 72 |
If given, *signum* is the number of the signal to simulate. |
| 73 |
If *signum* is not given, :const:`signal.SIGINT` is simulated. |
| 74 |
|
| 75 |
If the given signal isn't handled by Python (it was set to |
| 76 |
:const:`signal.SIG_DFL` or :const:`signal.SIG_IGN`), this function does |
| 77 |
nothing. |
| 78 |
|
| 79 |
.. versionchanged:: 3.10 |
| 80 |
The *signum* argument is added to customize the signal number. |
| 81 |
|
| 82 |
.. note:: |
| 83 |
This does not emit the corresponding signal but schedules a call to |
| 84 |
the associated handler (if it exists). |
| 85 |
If you want to truly emit the signal, use :func:`signal.raise_signal`. |
| 86 |
|
| 87 |
|
| 88 |
.. function:: exit() |
| 89 |
|
| 90 |
Raise the :exc:`SystemExit` exception. When not caught, this will cause the |
| 91 |
thread to exit silently. |
| 92 |
|
| 93 |
.. |
| 94 |
function:: exit_prog(status) |
| 95 |
|
| 96 |
Exit all threads and report the value of the integer argument |
| 97 |
*status* as the exit status of the entire program. |
| 98 |
**Caveat:** code in pending :keyword:`finally` clauses, in this thread |
| 99 |
or in other threads, is not executed. |
| 100 |
|
| 101 |
|
| 102 |
.. function:: allocate_lock() |
| 103 |
|
| 104 |
Return a new lock object. Methods of locks are described below. The lock is |
| 105 |
initially unlocked. |
| 106 |
|
| 107 |
|
| 108 |
.. function:: get_ident() |
| 109 |
|
| 110 |
Return the 'thread identifier' of the current thread. This is a nonzero |
| 111 |
integer. Its value has no direct meaning; it is intended as a magic cookie to |
| 112 |
be used e.g. to index a dictionary of thread-specific data. Thread identifiers |
| 113 |
may be recycled when a thread exits and another thread is created. |
| 114 |
|
| 115 |
|
| 116 |
.. function:: get_native_id() |
| 117 |
|
| 118 |
Return the native integral Thread ID of the current thread assigned by the kernel. |
| 119 |
This is a non-negative integer. |
| 120 |
Its value may be used to uniquely identify this particular thread system-wide |
| 121 |
(until the thread terminates, after which the value may be recycled by the OS). |
| 122 |
|
| 123 |
.. availability:: Windows, FreeBSD, Linux, macOS, OpenBSD, NetBSD, AIX, DragonFlyBSD, GNU/kFreeBSD. |
| 124 |
|
| 125 |
.. versionadded:: 3.8 |
| 126 |
|
| 127 |
.. versionchanged:: 3.13 |
| 128 |
Added support for GNU/kFreeBSD. |
| 129 |
|
| 130 |
|
| 131 |
.. function:: stack_size([size]) |
| 132 |
|
| 133 |
Return the thread stack size used when creating new threads. The optional |
| 134 |
*size* argument specifies the stack size to be used for subsequently created |
| 135 |
threads, and must be 0 (use platform or configured default) or a positive |
| 136 |
integer value of at least 32,768 (32 KiB). If *size* is not specified, |
| 137 |
0 is used. If changing the thread stack size is |
| 138 |
unsupported, a :exc:`RuntimeError` is raised. If the specified stack size is |
| 139 |
invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB |
| 140 |
is currently the minimum supported stack size value to guarantee sufficient |
| 141 |
stack space for the interpreter itself. Note that some platforms may have |
| 142 |
particular restrictions on values for the stack size, such as requiring a |
| 143 |
minimum stack size > 32 KiB or requiring allocation in multiples of the system |
| 144 |
memory page size - platform documentation should be referred to for more |
| 145 |
information (4 KiB pages are common; using multiples of 4096 for the stack size is |
| 146 |
the suggested approach in the absence of more specific information). |
| 147 |
|
| 148 |
.. availability:: Windows, pthreads. |
| 149 |
|
| 150 |
Unix platforms with POSIX threads support. |
| 151 |
|
| 152 |
|
| 153 |
.. data:: TIMEOUT_MAX |
| 154 |
|
| 155 |
The maximum value allowed for the *timeout* parameter of |
| 156 |
:meth:`Lock.acquire <threading.Lock.acquire>`. Specifying a timeout greater |
| 157 |
than this value will raise an :exc:`OverflowError`. |
| 158 |
|
| 159 |
.. versionadded:: 3.2 |
| 160 |
|
| 161 |
|
| 162 |
Lock objects have the following methods: |
| 163 |
|
| 164 |
|
| 165 |
.. method:: lock.acquire(blocking=True, timeout=-1) |
| 166 |
|
| 167 |
Without any optional argument, this method acquires the lock unconditionally, if |
| 168 |
necessary waiting until it is released by another thread (only one thread at a |
| 169 |
time can acquire a lock --- that's their reason for existence). |
| 170 |
|
| 171 |
If the *blocking* argument is present, the action depends on its |
| 172 |
value: if it is false, the lock is only acquired if it can be acquired |
| 173 |
immediately without waiting, while if it is true, the lock is acquired |
| 174 |
unconditionally as above. |
| 175 |
|
| 176 |
If the floating-point *timeout* argument is present and positive, it |
| 177 |
specifies the maximum wait time in seconds before returning. A negative |
| 178 |
*timeout* argument specifies an unbounded wait. You cannot specify |
| 179 |
a *timeout* if *blocking* is false. |
| 180 |
|
| 181 |
The return value is ``True`` if the lock is acquired successfully, |
| 182 |
``False`` if not. |
| 183 |
|
| 184 |
.. versionchanged:: 3.2 |
| 185 |
The *timeout* parameter is new. |
| 186 |
|
| 187 |
.. versionchanged:: 3.2 |
| 188 |
Lock acquires can now be interrupted by signals on POSIX. |
| 189 |
|
| 190 |
.. versionchanged:: 3.14 |
| 191 |
Lock acquires can now be interrupted by signals on Windows. |
| 192 |
|
| 193 |
|
| 194 |
.. method:: lock.release() |
| 195 |
|
| 196 |
Releases the lock. The lock must have been acquired earlier, but not |
| 197 |
necessarily by the same thread. |
| 198 |
|
| 199 |
|
| 200 |
.. method:: lock.locked() |
| 201 |
|
| 202 |
Return the status of the lock: ``True`` if it has been acquired by some thread, |
| 203 |
``False`` if not. |
| 204 |
|
| 205 |
In addition to these methods, lock objects can also be used via the |
| 206 |
:keyword:`with` statement, e.g.:: |
| 207 |
|
| 208 |
import _thread |
| 209 |
|
| 210 |
a_lock = _thread.allocate_lock() |
| 211 |
|
| 212 |
with a_lock: |
| 213 |
print("a_lock is locked while this executes") |
| 214 |
|
| 215 |
**Caveats:** |
| 216 |
|
| 217 |
.. index:: pair: module; signal |
| 218 |
|
| 219 |
* Interrupts always go to the main thread (the :exc:`KeyboardInterrupt` |
| 220 |
exception will be received by that thread.) |
| 221 |
|
| 222 |
* Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is |
| 223 |
equivalent to calling :func:`_thread.exit`. |
| 224 |
|
| 225 |
* When the main thread exits, it is system defined whether the other threads |
| 226 |
survive. On most systems, they are killed without executing |
| 227 |
:keyword:`try` ... :keyword:`finally` clauses or executing object |
| 228 |
destructors. |
| 229 |
|