1:mod:`thread` --- Multiple threads of control 2============================================= 3 4.. module:: thread 5 :synopsis: Create multiple threads of control within one interpreter. 6 7.. note:: 8 The :mod:`thread` module has been renamed to :mod:`_thread` in Python 3. 9 The :term:`2to3` tool will automatically adapt imports when converting your 10 sources to Python 3; however, you should consider using the high-level 11 :mod:`threading` module instead. 12 13 14.. index:: 15 single: light-weight processes 16 single: processes, light-weight 17 single: binary semaphores 18 single: semaphores, binary 19 20This module provides low-level primitives for working with multiple threads 21(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of 22control sharing their global data space. For synchronization, simple locks 23(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided. 24The :mod:`threading` module provides an easier to use and higher-level 25threading API built on top of this module. 26 27.. index:: 28 single: pthreads 29 pair: threads; POSIX 30 31The module is optional. It is supported on Windows, Linux, SGI IRIX, Solaris 322.x, as well as on systems that have a POSIX thread (a.k.a. "pthread") 33implementation. For systems lacking the :mod:`thread` module, the 34:mod:`dummy_thread` module is available. It duplicates this module's interface 35and can be used as a drop-in replacement. 36 37It defines the following constant and functions: 38 39 40.. exception:: error 41 42 Raised on thread-specific errors. 43 44 45.. data:: LockType 46 47 This is the type of lock objects. 48 49 50.. function:: start_new_thread(function, args[, kwargs]) 51 52 Start a new thread and return its identifier. The thread executes the function 53 *function* with the argument list *args* (which must be a tuple). The optional 54 *kwargs* argument specifies a dictionary of keyword arguments. When the function 55 returns, the thread silently exits. When the function terminates with an 56 unhandled exception, a stack trace is printed and then the thread exits (but 57 other threads continue to run). 58 59 60.. function:: interrupt_main() 61 62 Raise a :exc:`KeyboardInterrupt` exception in the main thread. A subthread can 63 use this function to interrupt the main thread. 64 65 .. versionadded:: 2.3 66 67 68.. function:: exit() 69 70 Raise the :exc:`SystemExit` exception. When not caught, this will cause the 71 thread to exit silently. 72 73.. 74 function:: exit_prog(status) 75 76 Exit all threads and report the value of the integer argument 77 *status* as the exit status of the entire program. 78 **Caveat:** code in pending :keyword:`finally` clauses, in this thread 79 or in other threads, is not executed. 80 81 82.. function:: allocate_lock() 83 84 Return a new lock object. Methods of locks are described below. The lock is 85 initially unlocked. 86 87 88.. function:: get_ident() 89 90 Return the 'thread identifier' of the current thread. This is a nonzero 91 integer. Its value has no direct meaning; it is intended as a magic cookie to 92 be used e.g. to index a dictionary of thread-specific data. Thread identifiers 93 may be recycled when a thread exits and another thread is created. 94 95 96.. function:: stack_size([size]) 97 98 Return the thread stack size used when creating new threads. The optional 99 *size* argument specifies the stack size to be used for subsequently created 100 threads, and must be 0 (use platform or configured default) or a positive 101 integer value of at least 32,768 (32kB). If *size* is not specified, 102 0 is used. If changing the thread stack size is 103 unsupported, the :exc:`error` exception is raised. If the specified stack size is 104 invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB 105 is currently the minimum supported stack size value to guarantee sufficient 106 stack space for the interpreter itself. Note that some platforms may have 107 particular restrictions on values for the stack size, such as requiring a 108 minimum stack size > 32kB or requiring allocation in multiples of the system 109 memory page size - platform documentation should be referred to for more 110 information (4kB pages are common; using multiples of 4096 for the stack size is 111 the suggested approach in the absence of more specific information). 112 Availability: Windows, systems with POSIX threads. 113 114 .. versionadded:: 2.5 115 116 117Lock objects have the following methods: 118 119 120.. method:: lock.acquire([waitflag]) 121 122 Without the optional argument, this method acquires the lock unconditionally, if 123 necessary waiting until it is released by another thread (only one thread at a 124 time can acquire a lock --- that's their reason for existence). If the integer 125 *waitflag* argument is present, the action depends on its value: if it is zero, 126 the lock is only acquired if it can be acquired immediately without waiting, 127 while if it is nonzero, the lock is acquired unconditionally as before. The 128 return value is ``True`` if the lock is acquired successfully, ``False`` if not. 129 130 131.. method:: lock.release() 132 133 Releases the lock. The lock must have been acquired earlier, but not 134 necessarily by the same thread. 135 136 137.. method:: lock.locked() 138 139 Return the status of the lock: ``True`` if it has been acquired by some thread, 140 ``False`` if not. 141 142In addition to these methods, lock objects can also be used via the 143:keyword:`with` statement, e.g.:: 144 145 import thread 146 147 a_lock = thread.allocate_lock() 148 149 with a_lock: 150 print "a_lock is locked while this executes" 151 152**Caveats:** 153 154 .. index:: module: signal 155 156* Threads interact strangely with interrupts: the :exc:`KeyboardInterrupt` 157 exception will be received by an arbitrary thread. (When the :mod:`signal` 158 module is available, interrupts always go to the main thread.) 159 160* Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is 161 equivalent to calling :func:`thread.exit`. 162 163* It is not possible to interrupt the :meth:`acquire` method on a lock --- the 164 :exc:`KeyboardInterrupt` exception will happen after the lock has been acquired. 165 166 .. index:: pair: threads; IRIX 167 168* When the main thread exits, it is system defined whether the other threads 169 survive. On SGI IRIX using the native thread implementation, they survive. On 170 most other systems, they are killed without executing :keyword:`try` ... 171 :keyword:`finally` clauses or executing object destructors. 172 173* When the main thread exits, it does not do any of its usual cleanup (except 174 that :keyword:`try` ... :keyword:`finally` clauses are honored), and the 175 standard I/O files are not flushed. 176 177