Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{thread} --- |
Fred Drake | 02e8c0f | 1999-04-21 18:01:14 +0000 | [diff] [blame] | 2 | Multiple threads of control} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | 02e8c0f | 1999-04-21 18:01:14 +0000 | [diff] [blame] | 4 | \declaremodule{builtin}{thread} |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 5 | \modulesynopsis{Create multiple threads of control within one interpreter.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 6 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 7 | |
| 8 | This module provides low-level primitives for working with multiple |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 9 | 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] | 10 | threads of control sharing their global data space. For |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 11 | synchronization, simple locks (a.k.a.\ \dfn{mutexes} or \dfn{binary |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 12 | semaphores}) are provided. |
Fred Drake | 61b0452 | 1998-01-20 05:52:23 +0000 | [diff] [blame] | 13 | \index{light-weight processes} |
| 14 | \index{processes, light-weight} |
| 15 | \index{binary semaphores} |
| 16 | \index{semaphores, binary} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 17 | |
Fred Drake | 7d428ec | 2002-10-22 15:06:49 +0000 | [diff] [blame] | 18 | The module is optional. It is supported on Windows, Linux, SGI |
Fred Drake | 65b32f7 | 1998-02-09 20:27:12 +0000 | [diff] [blame] | 19 | IRIX, Solaris 2.x, as well as on systems that have a \POSIX{} thread |
Guido van Rossum | 2969233 | 2002-12-30 22:34:10 +0000 | [diff] [blame] | 20 | (a.k.a. ``pthread'') implementation. For systems lacking the \module{thread} |
Fred Drake | 740f800 | 2002-12-30 23:00:36 +0000 | [diff] [blame] | 21 | module, the \refmodule[dummythread]{dummy_thread} module is available. |
| 22 | It duplicates this module's interface and can be |
| 23 | used as a drop-in replacement. |
Fred Drake | 61b0452 | 1998-01-20 05:52:23 +0000 | [diff] [blame] | 24 | \index{pthreads} |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 25 | \indexii{threads}{\POSIX} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 26 | |
| 27 | It defines the following constant and functions: |
| 28 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 29 | \begin{excdesc}{error} |
| 30 | Raised on thread-specific errors. |
| 31 | \end{excdesc} |
| 32 | |
Guido van Rossum | 73d8bff | 1998-06-27 18:25:44 +0000 | [diff] [blame] | 33 | \begin{datadesc}{LockType} |
| 34 | This is the type of lock objects. |
| 35 | \end{datadesc} |
| 36 | |
Fred Drake | 02e8c0f | 1999-04-21 18:01:14 +0000 | [diff] [blame] | 37 | \begin{funcdesc}{start_new_thread}{function, args\optional{, kwargs}} |
Guido van Rossum | 3c28863 | 2001-10-16 21:13:49 +0000 | [diff] [blame] | 38 | Start a new thread and return its identifier. The thread executes the function |
| 39 | \var{function} with the argument list \var{args} (which must be a tuple). The |
| 40 | optional \var{kwargs} argument specifies a dictionary of keyword arguments. |
| 41 | When the function returns, the thread silently exits. When the function |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 42 | terminates with an unhandled exception, a stack trace is printed and |
| 43 | then the thread exits (but other threads continue to run). |
| 44 | \end{funcdesc} |
| 45 | |
Kurt B. Kaiser | 0b1782f | 2003-07-08 17:07:20 +0000 | [diff] [blame] | 46 | \begin{funcdesc}{interrupt_main}{} |
| 47 | Raise a KeyboardInterrupt in the main thread. A subthread can use this |
Neal Norwitz | a4d2b86 | 2003-07-09 12:41:55 +0000 | [diff] [blame] | 48 | function to interrupt the main thread. |
| 49 | \versionadded{2.3} |
Kurt B. Kaiser | 0b1782f | 2003-07-08 17:07:20 +0000 | [diff] [blame] | 50 | \end{funcdesc} |
| 51 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 52 | \begin{funcdesc}{exit}{} |
Guido van Rossum | 73d8bff | 1998-06-27 18:25:44 +0000 | [diff] [blame] | 53 | Raise the \exception{SystemExit} exception. When not caught, this |
| 54 | will cause the thread to exit silently. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 55 | \end{funcdesc} |
| 56 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 57 | %\begin{funcdesc}{exit_prog}{status} |
| 58 | %Exit all threads and report the value of the integer argument |
| 59 | %\var{status} as the exit status of the entire program. |
Fred Drake | 02e8c0f | 1999-04-21 18:01:14 +0000 | [diff] [blame] | 60 | %\strong{Caveat:} code in pending \keyword{finally} clauses, in this thread |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 61 | %or in other threads, is not executed. |
| 62 | %\end{funcdesc} |
| 63 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 64 | \begin{funcdesc}{allocate_lock}{} |
| 65 | Return a new lock object. Methods of locks are described below. The |
| 66 | lock is initially unlocked. |
| 67 | \end{funcdesc} |
| 68 | |
Guido van Rossum | b8b264b | 1994-08-12 13:13:50 +0000 | [diff] [blame] | 69 | \begin{funcdesc}{get_ident}{} |
| 70 | Return the `thread identifier' of the current thread. This is a |
| 71 | nonzero integer. Its value has no direct meaning; it is intended as a |
| 72 | magic cookie to be used e.g. to index a dictionary of thread-specific |
| 73 | data. Thread identifiers may be recycled when a thread exits and |
| 74 | another thread is created. |
| 75 | \end{funcdesc} |
| 76 | |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 77 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 78 | Lock objects have the following methods: |
| 79 | |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 80 | \begin{methoddesc}[lock]{acquire}{\optional{waitflag}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 81 | Without the optional argument, this method acquires the lock |
| 82 | unconditionally, if necessary waiting until it is released by another |
| 83 | thread (only one thread at a time can acquire a lock --- that's their |
Andrew M. Kuchling | 921879a | 2005-06-02 16:59:18 +0000 | [diff] [blame] | 84 | reason for existence). If the integer |
Fred Drake | d61975e | 1998-11-30 16:26:50 +0000 | [diff] [blame] | 85 | \var{waitflag} argument is present, the action depends on its |
| 86 | value: if it is zero, the lock is only acquired if it can be acquired |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 87 | immediately without waiting, while if it is nonzero, the lock is |
Andrew M. Kuchling | 921879a | 2005-06-02 16:59:18 +0000 | [diff] [blame] | 88 | acquired unconditionally as before. The |
Neal Norwitz | 6b35370 | 2002-04-09 18:15:00 +0000 | [diff] [blame] | 89 | return value is \code{True} if the lock is acquired successfully, |
| 90 | \code{False} if not. |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 91 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 92 | |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 93 | \begin{methoddesc}[lock]{release}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 94 | Releases the lock. The lock must have been acquired earlier, but not |
| 95 | necessarily by the same thread. |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 96 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 97 | |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 98 | \begin{methoddesc}[lock]{locked}{} |
Neal Norwitz | 6b35370 | 2002-04-09 18:15:00 +0000 | [diff] [blame] | 99 | Return the status of the lock:\ \code{True} if it has been acquired by |
| 100 | some thread, \code{False} if not. |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 101 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 102 | |
Fred Drake | af8a015 | 1998-01-14 14:51:31 +0000 | [diff] [blame] | 103 | \strong{Caveats:} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 104 | |
| 105 | \begin{itemize} |
| 106 | \item |
| 107 | Threads interact strangely with interrupts: the |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 108 | \exception{KeyboardInterrupt} exception will be received by an |
Fred Drake | 02e8c0f | 1999-04-21 18:01:14 +0000 | [diff] [blame] | 109 | arbitrary thread. (When the \refmodule{signal}\refbimodindex{signal} |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 110 | module is available, interrupts always go to the main thread.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 111 | |
| 112 | \item |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 113 | Calling \function{sys.exit()} or raising the \exception{SystemExit} |
Fred Drake | 43b89b6 | 2000-04-05 15:00:38 +0000 | [diff] [blame] | 114 | exception is equivalent to calling \function{exit()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 115 | |
| 116 | \item |
| 117 | Not all built-in functions that may block waiting for I/O allow other |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 118 | threads to run. (The most popular ones (\function{time.sleep()}, |
| 119 | \method{\var{file}.read()}, \function{select.select()}) work as |
| 120 | expected.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 121 | |
Guido van Rossum | 3572d37 | 1997-08-14 19:51:26 +0000 | [diff] [blame] | 122 | \item |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 123 | It is not possible to interrupt the \method{acquire()} method on a lock |
| 124 | --- the \exception{KeyboardInterrupt} exception will happen after the |
| 125 | lock has been acquired. |
Guido van Rossum | 3572d37 | 1997-08-14 19:51:26 +0000 | [diff] [blame] | 126 | |
| 127 | \item |
| 128 | When the main thread exits, it is system defined whether the other |
| 129 | threads survive. On SGI IRIX using the native thread implementation, |
| 130 | they survive. On most other systems, they are killed without |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 131 | executing \keyword{try} ... \keyword{finally} clauses or executing |
| 132 | object destructors. |
Fred Drake | 61b0452 | 1998-01-20 05:52:23 +0000 | [diff] [blame] | 133 | \indexii{threads}{IRIX} |
Guido van Rossum | 3572d37 | 1997-08-14 19:51:26 +0000 | [diff] [blame] | 134 | |
| 135 | \item |
Fred Drake | d678cb7 | 1998-04-03 06:35:54 +0000 | [diff] [blame] | 136 | When the main thread exits, it does not do any of its usual cleanup |
| 137 | (except that \keyword{try} ... \keyword{finally} clauses are honored), |
| 138 | and the standard I/O files are not flushed. |
Guido van Rossum | 3572d37 | 1997-08-14 19:51:26 +0000 | [diff] [blame] | 139 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 140 | \end{itemize} |