Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{thread}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 2 | \label{module-thread} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 3 | \bimodindex{thread} |
| 4 | |
| 5 | This module provides low-level primitives for working with multiple |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 6 | threads (a.k.a.\ \dfn{light-weight processes} or \dfn{tasks}) --- multiple |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 7 | threads of control sharing their global data space. For |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 8 | synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 9 | semaphores}) are provided. |
| 10 | |
Guido van Rossum | 3572d37 | 1997-08-14 19:51:26 +0000 | [diff] [blame] | 11 | The module is optional. It is supported on Windows NT and '95, SGI |
| 12 | IRIX, Solaris 2.x, as well as on systems that have a POSIX thread |
| 13 | (a.k.a. ``pthread'') implementation. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 14 | |
| 15 | It defines the following constant and functions: |
| 16 | |
| 17 | \renewcommand{\indexsubitem}{(in module thread)} |
| 18 | \begin{excdesc}{error} |
| 19 | Raised on thread-specific errors. |
| 20 | \end{excdesc} |
| 21 | |
| 22 | \begin{funcdesc}{start_new_thread}{func\, arg} |
| 23 | Start a new thread. The thread executes the function \var{func} |
| 24 | with the argument list \var{arg} (which must be a tuple). When the |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 25 | function returns, the thread silently exits. When the function |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 26 | terminates with an unhandled exception, a stack trace is printed and |
| 27 | then the thread exits (but other threads continue to run). |
| 28 | \end{funcdesc} |
| 29 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 30 | \begin{funcdesc}{exit}{} |
| 31 | This is a shorthand for \code{thread.exit_thread()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 32 | \end{funcdesc} |
| 33 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 34 | \begin{funcdesc}{exit_thread}{} |
| 35 | Raise the \code{SystemExit} exception. When not caught, this will |
| 36 | cause the thread to exit silently. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 37 | \end{funcdesc} |
| 38 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 39 | %\begin{funcdesc}{exit_prog}{status} |
| 40 | %Exit all threads and report the value of the integer argument |
| 41 | %\var{status} as the exit status of the entire program. |
| 42 | %\strong{Caveat:} code in pending \code{finally} clauses, in this thread |
| 43 | %or in other threads, is not executed. |
| 44 | %\end{funcdesc} |
| 45 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 46 | \begin{funcdesc}{allocate_lock}{} |
| 47 | Return a new lock object. Methods of locks are described below. The |
| 48 | lock is initially unlocked. |
| 49 | \end{funcdesc} |
| 50 | |
Guido van Rossum | b8b264b | 1994-08-12 13:13:50 +0000 | [diff] [blame] | 51 | \begin{funcdesc}{get_ident}{} |
| 52 | Return the `thread identifier' of the current thread. This is a |
| 53 | nonzero integer. Its value has no direct meaning; it is intended as a |
| 54 | magic cookie to be used e.g. to index a dictionary of thread-specific |
| 55 | data. Thread identifiers may be recycled when a thread exits and |
| 56 | another thread is created. |
| 57 | \end{funcdesc} |
| 58 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 59 | Lock objects have the following methods: |
| 60 | |
| 61 | \renewcommand{\indexsubitem}{(lock method)} |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 62 | \begin{funcdesc}{acquire}{\optional{waitflag}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 63 | Without the optional argument, this method acquires the lock |
| 64 | unconditionally, if necessary waiting until it is released by another |
| 65 | thread (only one thread at a time can acquire a lock --- that's their |
| 66 | reason for existence), and returns \code{None}. If the integer |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 67 | \var{waitflag} argument is present, the action depends on its value:\ |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 68 | if it is zero, the lock is only acquired if it can be acquired |
| 69 | immediately without waiting, while if it is nonzero, the lock is |
| 70 | acquired unconditionally as before. If an argument is present, the |
| 71 | return value is 1 if the lock is acquired successfully, 0 if not. |
| 72 | \end{funcdesc} |
| 73 | |
| 74 | \begin{funcdesc}{release}{} |
| 75 | Releases the lock. The lock must have been acquired earlier, but not |
| 76 | necessarily by the same thread. |
| 77 | \end{funcdesc} |
| 78 | |
| 79 | \begin{funcdesc}{locked}{} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 80 | Return the status of the lock:\ 1 if it has been acquired by some |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 81 | thread, 0 if not. |
| 82 | \end{funcdesc} |
| 83 | |
| 84 | {\bf Caveats:} |
| 85 | |
| 86 | \begin{itemize} |
| 87 | \item |
| 88 | Threads interact strangely with interrupts: the |
| 89 | \code{KeyboardInterrupt} exception will be received by an arbitrary |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 90 | thread. (When the \code{signal} module is available, interrupts |
| 91 | always go to the main thread.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 92 | |
| 93 | \item |
Guido van Rossum | 3572d37 | 1997-08-14 19:51:26 +0000 | [diff] [blame] | 94 | Calling \code{sys.exit()} or raising the \code{SystemExit} exception is |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 95 | equivalent to calling \code{thread.exit_thread()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 96 | |
| 97 | \item |
| 98 | Not all built-in functions that may block waiting for I/O allow other |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 99 | threads to run. (The most popular ones (\code{sleep}, \code{read}, |
| 100 | \code{select}) work as expected.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 101 | |
Guido van Rossum | 3572d37 | 1997-08-14 19:51:26 +0000 | [diff] [blame] | 102 | \item |
| 103 | It is not possible to interrupt the \code{acquire()} method on a lock |
| 104 | -- the \code{KeyboardInterrupt} exception will happen after the lock |
| 105 | has been acquired. |
| 106 | |
| 107 | \item |
| 108 | When the main thread exits, it is system defined whether the other |
| 109 | threads survive. On SGI IRIX using the native thread implementation, |
| 110 | they survive. On most other systems, they are killed without |
| 111 | executing ``try-finally'' clauses or executing object destructors. |
| 112 | |
| 113 | \item |
| 114 | When the main thread exits, it doesn't do any of its usual cleanup |
| 115 | (except that ``try-finally'' clauses are honored), and the standard |
| 116 | I/O files are not flushed. |
| 117 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 118 | \end{itemize} |