Mercurial > cpython-lru_cache-weakref

annotate Doc/library/_thread.rst @ 78069:a8aa77458e12 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add c_size_t and c_ssize_t to the ctypes summary table.
author Antoine Pitrou <solipsis@pitrou.net>
date Thu, 12 Jul 2012 20:31:50 +0200
parents b750c45a772c
children 2ddca55e098d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
47266
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
1 :mod:`_thread` --- Low-level threading API
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
2 ==========================================
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
47266
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
4 .. module:: _thread
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
5 :synopsis: Low-level threading API.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 single: light-weight processes
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 single: processes, light-weight
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 single: binary semaphores
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 single: semaphores, binary
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 This module provides low-level primitives for working with multiple threads
43292
876b7ef4775d Merged revisions 57778-58052 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43197
diff changeset
15 (also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 control sharing their global data space. For synchronization, simple locks
43292
876b7ef4775d Merged revisions 57778-58052 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43197
diff changeset
17 (also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.
876b7ef4775d Merged revisions 57778-58052 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43197
diff changeset
18 The :mod:`threading` module provides an easier to use and higher-level
876b7ef4775d Merged revisions 57778-58052 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43197
diff changeset
19 threading API built on top of this module.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 single: pthreads
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 pair: threads; POSIX
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 The module is optional. It is supported on Windows, Linux, SGI IRIX, Solaris
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 2.x, as well as on systems that have a POSIX thread (a.k.a. "pthread")
47266
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
27 implementation. For systems lacking the :mod:`_thread` module, the
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
28 :mod:`_dummy_thread` module is available. It duplicates this module's interface
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 and can be used as a drop-in replacement.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
31 It defines the following constants and functions:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 .. exception:: error
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 Raised on thread-specific errors.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 .. data:: LockType
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 This is the type of lock objects.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 .. function:: start_new_thread(function, args[, kwargs])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 Start a new thread and return its identifier. The thread executes the function
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 *function* with the argument list *args* (which must be a tuple). The optional
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 *kwargs* argument specifies a dictionary of keyword arguments. When the function
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 returns, the thread silently exits. When the function terminates with an
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 unhandled exception, a stack trace is printed and then the thread exits (but
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 other threads continue to run).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 .. function:: interrupt_main()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 Raise a :exc:`KeyboardInterrupt` exception in the main thread. A subthread can
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 use this function to interrupt the main thread.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 .. function:: exit()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 Raise the :exc:`SystemExit` exception. When not caught, this will cause the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 thread to exit silently.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64
44396
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43292
diff changeset
65 ..
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43292
diff changeset
66 function:: exit_prog(status)
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43292
diff changeset
67
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43292
diff changeset
68 Exit all threads and report the value of the integer argument
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43292
diff changeset
69 *status* as the exit status of the entire program.
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43292
diff changeset
70 **Caveat:** code in pending :keyword:`finally` clauses, in this thread
6556f3f22c19 Merged revisions 59605-59624 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43292
diff changeset
71 or in other threads, is not executed.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 .. function:: allocate_lock()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 Return a new lock object. Methods of locks are described below. The lock is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 initially unlocked.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 .. function:: get_ident()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 Return the 'thread identifier' of the current thread. This is a nonzero
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 integer. Its value has no direct meaning; it is intended as a magic cookie to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 be used e.g. to index a dictionary of thread-specific data. Thread identifiers
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 may be recycled when a thread exits and another thread is created.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 .. function:: stack_size([size])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 Return the thread stack size used when creating new threads. The optional
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 *size* argument specifies the stack size to be used for subsequently created
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 threads, and must be 0 (use platform or configured default) or a positive
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 integer value of at least 32,768 (32kB). If changing the thread stack size is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 unsupported, a :exc:`ThreadError` is raised. If the specified stack size is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 is currently the minimum supported stack size value to guarantee sufficient
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 stack space for the interpreter itself. Note that some platforms may have
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 particular restrictions on values for the stack size, such as requiring a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 minimum stack size > 32kB or requiring allocation in multiples of the system
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 memory page size - platform documentation should be referred to for more
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 information (4kB pages are common; using multiples of 4096 for the stack size is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 the suggested approach in the absence of more specific information).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 Availability: Windows, systems with POSIX threads.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
106 .. data:: TIMEOUT_MAX
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
107
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
108 The maximum value allowed for the *timeout* parameter of
64875
d6d655fddf22 #9911: doc copyedits.
Georg Brandl <georg@python.org>
parents: 60719
diff changeset
109 :meth:`Lock.acquire`. Specifying a timeout greater than this value will
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
110 raise an :exc:`OverflowError`.
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
111
60718
7a564d74fd4a Add version{added,changed} for lock timeout support.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60598
diff changeset
112 .. versionadded:: 3.2
7a564d74fd4a Add version{added,changed} for lock timeout support.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60598
diff changeset
113
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
114
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 Lock objects have the following methods:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
118 .. method:: lock.acquire(waitflag=1, timeout=-1)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
120 Without any optional argument, this method acquires the lock unconditionally, if
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 necessary waiting until it is released by another thread (only one thread at a
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
122 time can acquire a lock --- that's their reason for existence).
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
123
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
124 If the integer *waitflag* argument is present, the action depends on its
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
125 value: if it is zero, the lock is only acquired if it can be acquired
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
126 immediately without waiting, while if it is nonzero, the lock is acquired
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
127 unconditionally as above.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
60598
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
129 If the floating-point *timeout* argument is present and positive, it
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
130 specifies the maximum wait time in seconds before returning. A negative
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
131 *timeout* argument specifies an unbounded wait. You cannot specify
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
132 a *timeout* if *waitflag* is zero.
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
133
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
134 The return value is ``True`` if the lock is acquired successfully,
01d1fd775d16 Issue #7316: the acquire() method of lock objects in the :mod:`threading`
Antoine Pitrou <solipsis@pitrou.net>
parents: 56992
diff changeset
135 ``False`` if not.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
60718
7a564d74fd4a Add version{added,changed} for lock timeout support.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60598
diff changeset
137 .. versionchanged:: 3.2
7a564d74fd4a Add version{added,changed} for lock timeout support.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60598
diff changeset
138 The *timeout* parameter is new.
7a564d74fd4a Add version{added,changed} for lock timeout support.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60598
diff changeset
139
66946
b750c45a772c Issue #8844: Regular and recursive lock acquisitions can now be interrupted
Antoine Pitrou <solipsis@pitrou.net>
parents: 64875
diff changeset
140 .. versionchanged:: 3.2
b750c45a772c Issue #8844: Regular and recursive lock acquisitions can now be interrupted
Antoine Pitrou <solipsis@pitrou.net>
parents: 64875
diff changeset
141 Lock acquires can now be interrupted by signals on POSIX.
b750c45a772c Issue #8844: Regular and recursive lock acquisitions can now be interrupted
Antoine Pitrou <solipsis@pitrou.net>
parents: 64875
diff changeset
142
b750c45a772c Issue #8844: Regular and recursive lock acquisitions can now be interrupted
Antoine Pitrou <solipsis@pitrou.net>
parents: 64875
diff changeset
143
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 .. method:: lock.release()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 Releases the lock. The lock must have been acquired earlier, but not
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 necessarily by the same thread.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 .. method:: lock.locked()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 Return the status of the lock: ``True`` if it has been acquired by some thread,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 ``False`` if not.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 In addition to these methods, lock objects can also be used via the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 :keyword:`with` statement, e.g.::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
47266
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
158 import _thread
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
47266
7fe3a8648ce2 Rename thread to _thread and dummy_thread to _dummy_thread. Issue #2875.
Georg Brandl <georg@python.org>
parents: 45534
diff changeset
160 a_lock = _thread.allocate_lock()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 with a_lock:
43197
1b0d15444ca5 Partial py3k-ification of Doc/library/: convert has_key references into either 'k in d' or __contains__; normalize raise statements; convert print statements into print function calls.
Collin Winter <collinw@gmail.com>
parents: 43176
diff changeset
163 print("a_lock is locked while this executes")
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 **Caveats:**
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 .. index:: module: signal
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 * Threads interact strangely with interrupts: the :exc:`KeyboardInterrupt`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 exception will be received by an arbitrary thread. (When the :mod:`signal`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 module is available, interrupts always go to the main thread.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 * Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is
55797
afbb2b2ff6f7 Merged revisions 74613,74615,74619-74620,74622 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47266
diff changeset
174 equivalent to calling :func:`_thread.exit`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 * Not all built-in functions that may block waiting for I/O allow other threads
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 to run. (The most popular ones (:func:`time.sleep`, :meth:`file.read`,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 :func:`select.select`) work as expected.)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 * It is not possible to interrupt the :meth:`acquire` method on a lock --- the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 :exc:`KeyboardInterrupt` exception will happen after the lock has been acquired.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 * When the main thread exits, it is system defined whether the other threads
60719
789612cd0970 Remove obsolete mention of IRIX native threads -- we don't use them anymore.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60718
diff changeset
184 survive. On most systems, they are killed without executing
789612cd0970 Remove obsolete mention of IRIX native threads -- we don't use them anymore.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60718
diff changeset
185 :keyword:`try` ... :keyword:`finally` clauses or executing object
789612cd0970 Remove obsolete mention of IRIX native threads -- we don't use them anymore.
Antoine Pitrou <solipsis@pitrou.net>
parents: 60718
diff changeset
186 destructors.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 * When the main thread exits, it does not do any of its usual cleanup (except
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 that :keyword:`try` ... :keyword:`finally` clauses are honored), and the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 standard I/O files are not flushed.
45534
7afef8f43e4a Merged revisions 61038,61042-61045,61047,61050,61053,61055-61056,61061-61064,61066-61080 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 45495
diff changeset
191