blob: cb09afaa6635d81d1ecb2ba718104eb418f8701e [file] [log] [blame]
Jeremy Hylton92bb6e72002-08-14 19:25:42 +00001"""Thread module emulating a subset of Java's threading model."""
Guido van Rossum7f5013a1998-04-09 22:01:42 +00002
Fred Drakea8725952002-12-30 23:32:50 +00003import sys as _sys
Georg Brandl2067bfd2008-05-25 13:05:15 +00004import _thread
Fred Drakea8725952002-12-30 23:32:50 +00005
Fred Drakea8725952002-12-30 23:32:50 +00006from time import time as _time, sleep as _sleep
Neil Schemenauerf607fc52003-11-05 23:03:00 +00007from traceback import format_exc as _format_exc
Raymond Hettinger756b3f32004-01-29 06:37:52 +00008from collections import deque
Guido van Rossum7f5013a1998-04-09 22:01:42 +00009
Benjamin Petersonb3085c92008-09-01 23:09:31 +000010# Note regarding PEP 8 compliant names
11# This threading model was originally inspired by Java, and inherited
12# the convention of camelCase function and method names from that
13# language. Those originaly names are not in any imminent danger of
14# being deprecated (even for Py3k),so this module provides them as an
15# alias for the PEP 8 compliant names
16# Note that using the new PEP 8 compliant names facilitates substitution
17# with the multiprocessing module, which doesn't provide the old
18# Java inspired names.
19
Benjamin Peterson672b8032008-06-11 19:14:14 +000020__all__ = ['active_count', 'Condition', 'current_thread', 'enumerate', 'Event',
Raymond Hettinger5cee47f2011-01-11 19:59:46 +000021 'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Thread', 'Barrier',
Thomas Wouters0e3f5912006-08-11 14:57:12 +000022 'Timer', 'setprofile', 'settrace', 'local', 'stack_size']
Guido van Rossum7f5013a1998-04-09 22:01:42 +000023
Raymond Hettinger5cee47f2011-01-11 19:59:46 +000024# Rename some stuff so "from threading import *" is safe
Georg Brandl2067bfd2008-05-25 13:05:15 +000025_start_new_thread = _thread.start_new_thread
26_allocate_lock = _thread.allocate_lock
27_get_ident = _thread.get_ident
28ThreadError = _thread.error
Antoine Pitrou434736a2009-11-10 18:46:01 +000029try:
30 _CRLock = _thread.RLock
31except AttributeError:
32 _CRLock = None
Antoine Pitrou7c3e5772010-04-14 15:44:10 +000033TIMEOUT_MAX = _thread.TIMEOUT_MAX
Georg Brandl2067bfd2008-05-25 13:05:15 +000034del _thread
Guido van Rossum7f5013a1998-04-09 22:01:42 +000035
Guido van Rossum7f5013a1998-04-09 22:01:42 +000036
Tim Peters59aba122003-07-01 20:01:55 +000037# Debug support (adapted from ihooks.py).
Guido van Rossum7f5013a1998-04-09 22:01:42 +000038
Tim Peters0939fac2003-07-01 19:28:44 +000039_VERBOSE = False
Guido van Rossum7f5013a1998-04-09 22:01:42 +000040
41if __debug__:
42
Tim Peters59aba122003-07-01 20:01:55 +000043 class _Verbose(object):
Guido van Rossum7f5013a1998-04-09 22:01:42 +000044
45 def __init__(self, verbose=None):
46 if verbose is None:
47 verbose = _VERBOSE
Guido van Rossumd0648992007-08-20 19:25:41 +000048 self._verbose = verbose
Guido van Rossum7f5013a1998-04-09 22:01:42 +000049
50 def _note(self, format, *args):
Guido van Rossumd0648992007-08-20 19:25:41 +000051 if self._verbose:
Guido van Rossum7f5013a1998-04-09 22:01:42 +000052 format = format % args
Antoine Pitrou401edd62010-12-17 17:42:16 +000053 # Issue #4188: calling current_thread() can incur an infinite
54 # recursion if it has to create a DummyThread on the fly.
55 ident = _get_ident()
56 try:
57 name = _active[ident].name
58 except KeyError:
59 name = "<OS thread %d>" % ident
60 format = "%s: %s\n" % (name, format)
Guido van Rossum7f5013a1998-04-09 22:01:42 +000061 _sys.stderr.write(format)
62
63else:
64 # Disable this when using "python -O"
Tim Peters59aba122003-07-01 20:01:55 +000065 class _Verbose(object):
Guido van Rossum7f5013a1998-04-09 22:01:42 +000066 def __init__(self, verbose=None):
67 pass
68 def _note(self, *args):
69 pass
70
Jeremy Hyltonbfccb352003-06-29 16:58:41 +000071# Support for profile and trace hooks
72
73_profile_hook = None
74_trace_hook = None
75
76def setprofile(func):
77 global _profile_hook
78 _profile_hook = func
Tim Petersd1b108b2003-06-29 17:24:17 +000079
Jeremy Hyltonbfccb352003-06-29 16:58:41 +000080def settrace(func):
81 global _trace_hook
82 _trace_hook = func
Guido van Rossum7f5013a1998-04-09 22:01:42 +000083
84# Synchronization classes
85
86Lock = _allocate_lock
87
Antoine Pitrou434736a2009-11-10 18:46:01 +000088def RLock(verbose=None, *args, **kwargs):
89 if verbose is None:
90 verbose = _VERBOSE
91 if (__debug__ and verbose) or _CRLock is None:
92 return _PyRLock(verbose, *args, **kwargs)
93 return _CRLock(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +000094
95class _RLock(_Verbose):
Tim Petersb90f89a2001-01-15 03:26:36 +000096
Guido van Rossum7f5013a1998-04-09 22:01:42 +000097 def __init__(self, verbose=None):
98 _Verbose.__init__(self, verbose)
Guido van Rossumd0648992007-08-20 19:25:41 +000099 self._block = _allocate_lock()
100 self._owner = None
101 self._count = 0
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000102
103 def __repr__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000104 owner = self._owner
Antoine Pitroub0872682009-11-09 16:08:16 +0000105 try:
106 owner = _active[owner].name
107 except KeyError:
108 pass
109 return "<%s owner=%r count=%d>" % (
110 self.__class__.__name__, owner, self._count)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000111
Antoine Pitrou7c3e5772010-04-14 15:44:10 +0000112 def acquire(self, blocking=True, timeout=-1):
Antoine Pitroub0872682009-11-09 16:08:16 +0000113 me = _get_ident()
114 if self._owner == me:
Guido van Rossumd0648992007-08-20 19:25:41 +0000115 self._count = self._count + 1
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000116 if __debug__:
117 self._note("%s.acquire(%s): recursive success", self, blocking)
118 return 1
Antoine Pitrou7c3e5772010-04-14 15:44:10 +0000119 rc = self._block.acquire(blocking, timeout)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000120 if rc:
Guido van Rossumd0648992007-08-20 19:25:41 +0000121 self._owner = me
122 self._count = 1
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000123 if __debug__:
Brett Cannon90cece72005-01-27 22:48:30 +0000124 self._note("%s.acquire(%s): initial success", self, blocking)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000125 else:
126 if __debug__:
127 self._note("%s.acquire(%s): failure", self, blocking)
128 return rc
129
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000130 __enter__ = acquire
131
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000132 def release(self):
Antoine Pitroub0872682009-11-09 16:08:16 +0000133 if self._owner != _get_ident():
Georg Brandl495f7b52009-10-27 15:28:25 +0000134 raise RuntimeError("cannot release un-acquired lock")
Guido van Rossumd0648992007-08-20 19:25:41 +0000135 self._count = count = self._count - 1
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000136 if not count:
Guido van Rossumd0648992007-08-20 19:25:41 +0000137 self._owner = None
138 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000139 if __debug__:
140 self._note("%s.release(): final release", self)
141 else:
142 if __debug__:
143 self._note("%s.release(): non-final release", self)
144
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000145 def __exit__(self, t, v, tb):
146 self.release()
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000147
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000148 # Internal methods used by condition variables
149
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000150 def _acquire_restore(self, state):
Guido van Rossumd0648992007-08-20 19:25:41 +0000151 self._block.acquire()
152 self._count, self._owner = state
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000153 if __debug__:
154 self._note("%s._acquire_restore()", self)
155
156 def _release_save(self):
157 if __debug__:
158 self._note("%s._release_save()", self)
Guido van Rossumd0648992007-08-20 19:25:41 +0000159 count = self._count
160 self._count = 0
161 owner = self._owner
162 self._owner = None
163 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000164 return (count, owner)
165
166 def _is_owned(self):
Antoine Pitroub0872682009-11-09 16:08:16 +0000167 return self._owner == _get_ident()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000168
Antoine Pitrou434736a2009-11-10 18:46:01 +0000169_PyRLock = _RLock
170
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000171
172def Condition(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000173 return _Condition(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000174
175class _Condition(_Verbose):
176
177 def __init__(self, lock=None, verbose=None):
178 _Verbose.__init__(self, verbose)
179 if lock is None:
180 lock = RLock()
Guido van Rossumd0648992007-08-20 19:25:41 +0000181 self._lock = lock
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000182 # Export the lock's acquire() and release() methods
183 self.acquire = lock.acquire
184 self.release = lock.release
185 # If the lock defines _release_save() and/or _acquire_restore(),
186 # these override the default implementations (which just call
187 # release() and acquire() on the lock). Ditto for _is_owned().
188 try:
189 self._release_save = lock._release_save
190 except AttributeError:
191 pass
192 try:
193 self._acquire_restore = lock._acquire_restore
194 except AttributeError:
195 pass
196 try:
197 self._is_owned = lock._is_owned
198 except AttributeError:
199 pass
Guido van Rossumd0648992007-08-20 19:25:41 +0000200 self._waiters = []
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000201
Thomas Wouters477c8d52006-05-27 19:21:47 +0000202 def __enter__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000203 return self._lock.__enter__()
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000204
Thomas Wouters477c8d52006-05-27 19:21:47 +0000205 def __exit__(self, *args):
Guido van Rossumd0648992007-08-20 19:25:41 +0000206 return self._lock.__exit__(*args)
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000207
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000208 def __repr__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000209 return "<Condition(%s, %d)>" % (self._lock, len(self._waiters))
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000210
211 def _release_save(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000212 self._lock.release() # No state to save
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000213
214 def _acquire_restore(self, x):
Guido van Rossumd0648992007-08-20 19:25:41 +0000215 self._lock.acquire() # Ignore saved state
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000216
217 def _is_owned(self):
Benjamin Peterson672b8032008-06-11 19:14:14 +0000218 # Return True if lock is owned by current_thread.
Jeremy Hyltonaf7fde72002-08-14 17:43:59 +0000219 # This method is called only if __lock doesn't have _is_owned().
Guido van Rossumd0648992007-08-20 19:25:41 +0000220 if self._lock.acquire(0):
221 self._lock.release()
Tim Petersbc0e9102002-04-04 22:55:58 +0000222 return False
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000223 else:
Tim Petersbc0e9102002-04-04 22:55:58 +0000224 return True
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000225
226 def wait(self, timeout=None):
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000227 if not self._is_owned():
Georg Brandl495f7b52009-10-27 15:28:25 +0000228 raise RuntimeError("cannot wait on un-acquired lock")
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000229 waiter = _allocate_lock()
230 waiter.acquire()
Guido van Rossumd0648992007-08-20 19:25:41 +0000231 self._waiters.append(waiter)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000232 saved_state = self._release_save()
Tim Petersc951bf92001-04-02 20:15:57 +0000233 try: # restore state no matter what (e.g., KeyboardInterrupt)
234 if timeout is None:
235 waiter.acquire()
Georg Brandlb9a43912010-10-28 09:03:20 +0000236 gotit = True
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000237 if __debug__:
Tim Petersc951bf92001-04-02 20:15:57 +0000238 self._note("%s.wait(): got it", self)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000239 else:
Antoine Pitrou7c3e5772010-04-14 15:44:10 +0000240 if timeout > 0:
241 gotit = waiter.acquire(True, timeout)
242 else:
243 gotit = waiter.acquire(False)
Tim Petersc951bf92001-04-02 20:15:57 +0000244 if not gotit:
245 if __debug__:
246 self._note("%s.wait(%s): timed out", self, timeout)
247 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000248 self._waiters.remove(waiter)
Tim Petersc951bf92001-04-02 20:15:57 +0000249 except ValueError:
250 pass
251 else:
252 if __debug__:
253 self._note("%s.wait(%s): got it", self, timeout)
Georg Brandlb9a43912010-10-28 09:03:20 +0000254 return gotit
Tim Petersc951bf92001-04-02 20:15:57 +0000255 finally:
256 self._acquire_restore(saved_state)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000257
Kristján Valur Jónsson63315202010-11-18 12:46:39 +0000258 def wait_for(self, predicate, timeout=None):
259 endtime = None
260 waittime = timeout
261 result = predicate()
262 while not result:
263 if waittime is not None:
264 if endtime is None:
265 endtime = _time() + waittime
266 else:
267 waittime = endtime - _time()
268 if waittime <= 0:
269 if __debug__:
270 self._note("%s.wait_for(%r, %r): Timed out.",
271 self, predicate, timeout)
272 break
273 if __debug__:
274 self._note("%s.wait_for(%r, %r): Waiting with timeout=%s.",
275 self, predicate, timeout, waittime)
276 self.wait(waittime)
277 result = predicate()
278 else:
279 if __debug__:
280 self._note("%s.wait_for(%r, %r): Success.",
281 self, predicate, timeout)
282 return result
283
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000284 def notify(self, n=1):
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000285 if not self._is_owned():
Georg Brandl495f7b52009-10-27 15:28:25 +0000286 raise RuntimeError("cannot notify on un-acquired lock")
Guido van Rossumd0648992007-08-20 19:25:41 +0000287 __waiters = self._waiters
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000288 waiters = __waiters[:n]
289 if not waiters:
290 if __debug__:
291 self._note("%s.notify(): no waiters", self)
292 return
293 self._note("%s.notify(): notifying %d waiter%s", self, n,
294 n!=1 and "s" or "")
295 for waiter in waiters:
296 waiter.release()
297 try:
298 __waiters.remove(waiter)
299 except ValueError:
300 pass
301
Benjamin Peterson672b8032008-06-11 19:14:14 +0000302 def notify_all(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000303 self.notify(len(self._waiters))
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000304
Benjamin Petersonb3085c92008-09-01 23:09:31 +0000305 notifyAll = notify_all
306
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000307
308def Semaphore(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000309 return _Semaphore(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000310
311class _Semaphore(_Verbose):
312
Andrew M. Kuchling39d3bfc2000-02-29 00:10:24 +0000313 # After Tim Peters' semaphore class, but not quite the same (no maximum)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000314
315 def __init__(self, value=1, verbose=None):
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000316 if value < 0:
317 raise ValueError("semaphore initial value must be >= 0")
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000318 _Verbose.__init__(self, verbose)
Guido van Rossumd0648992007-08-20 19:25:41 +0000319 self._cond = Condition(Lock())
320 self._value = value
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000321
Antoine Pitrou0454af92010-04-17 23:51:58 +0000322 def acquire(self, blocking=True, timeout=None):
323 if not blocking and timeout is not None:
324 raise ValueError("can't specify timeout for non-blocking acquire")
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000325 rc = False
Antoine Pitrou0454af92010-04-17 23:51:58 +0000326 endtime = None
Guido van Rossumd0648992007-08-20 19:25:41 +0000327 self._cond.acquire()
328 while self._value == 0:
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000329 if not blocking:
330 break
Skip Montanarob446fc72001-08-19 04:25:24 +0000331 if __debug__:
332 self._note("%s.acquire(%s): blocked waiting, value=%s",
Guido van Rossumd0648992007-08-20 19:25:41 +0000333 self, blocking, self._value)
Antoine Pitrou0454af92010-04-17 23:51:58 +0000334 if timeout is not None:
335 if endtime is None:
336 endtime = _time() + timeout
337 else:
338 timeout = endtime - _time()
339 if timeout <= 0:
340 break
341 self._cond.wait(timeout)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000342 else:
Guido van Rossumd0648992007-08-20 19:25:41 +0000343 self._value = self._value - 1
Skip Montanarob446fc72001-08-19 04:25:24 +0000344 if __debug__:
Skip Montanaroae8454a2001-08-19 05:53:47 +0000345 self._note("%s.acquire: success, value=%s",
Guido van Rossumd0648992007-08-20 19:25:41 +0000346 self, self._value)
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000347 rc = True
Guido van Rossumd0648992007-08-20 19:25:41 +0000348 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000349 return rc
350
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000351 __enter__ = acquire
352
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000353 def release(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000354 self._cond.acquire()
355 self._value = self._value + 1
Skip Montanarob446fc72001-08-19 04:25:24 +0000356 if __debug__:
Skip Montanaroae8454a2001-08-19 05:53:47 +0000357 self._note("%s.release: success, value=%s",
Guido van Rossumd0648992007-08-20 19:25:41 +0000358 self, self._value)
359 self._cond.notify()
360 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000361
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000362 def __exit__(self, t, v, tb):
363 self.release()
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000364
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000365
Skip Montanaroe428bb72001-08-20 20:27:58 +0000366def BoundedSemaphore(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000367 return _BoundedSemaphore(*args, **kwargs)
Skip Montanaroe428bb72001-08-20 20:27:58 +0000368
369class _BoundedSemaphore(_Semaphore):
370 """Semaphore that checks that # releases is <= # acquires"""
371 def __init__(self, value=1, verbose=None):
372 _Semaphore.__init__(self, value, verbose)
373 self._initial_value = value
374
375 def release(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000376 if self._value >= self._initial_value:
Collin Winterce36ad82007-08-30 01:19:48 +0000377 raise ValueError("Semaphore released too many times")
Skip Montanaroe428bb72001-08-20 20:27:58 +0000378 return _Semaphore.release(self)
379
380
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000381def Event(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000382 return _Event(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000383
384class _Event(_Verbose):
385
386 # After Tim Peters' event class (without is_posted())
387
388 def __init__(self, verbose=None):
389 _Verbose.__init__(self, verbose)
Guido van Rossumd0648992007-08-20 19:25:41 +0000390 self._cond = Condition(Lock())
391 self._flag = False
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000392
Gregory P. Smith9bd4a242011-01-04 18:33:38 +0000393 def _reset_internal_locks(self):
394 # private! called by Thread._reset_internal_locks by _after_fork()
395 self._cond.__init__()
396
Benjamin Peterson672b8032008-06-11 19:14:14 +0000397 def is_set(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000398 return self._flag
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000399
Benjamin Petersonb3085c92008-09-01 23:09:31 +0000400 isSet = is_set
Benjamin Petersonf0923f52008-08-18 22:10:13 +0000401
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000402 def set(self):
Christian Heimes969fe572008-01-25 11:23:10 +0000403 self._cond.acquire()
404 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000405 self._flag = True
Benjamin Peterson672b8032008-06-11 19:14:14 +0000406 self._cond.notify_all()
Christian Heimes969fe572008-01-25 11:23:10 +0000407 finally:
408 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000409
410 def clear(self):
Christian Heimes969fe572008-01-25 11:23:10 +0000411 self._cond.acquire()
412 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000413 self._flag = False
Christian Heimes969fe572008-01-25 11:23:10 +0000414 finally:
415 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000416
417 def wait(self, timeout=None):
Christian Heimes969fe572008-01-25 11:23:10 +0000418 self._cond.acquire()
419 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000420 if not self._flag:
421 self._cond.wait(timeout)
Benjamin Petersond23f8222009-04-05 19:13:16 +0000422 return self._flag
Christian Heimes969fe572008-01-25 11:23:10 +0000423 finally:
424 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000425
Kristján Valur Jónsson3be00032010-10-28 09:43:10 +0000426
427# A barrier class. Inspired in part by the pthread_barrier_* api and
428# the CyclicBarrier class from Java. See
429# http://sourceware.org/pthreads-win32/manual/pthread_barrier_init.html and
430# http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/
431# CyclicBarrier.html
432# for information.
433# We maintain two main states, 'filling' and 'draining' enabling the barrier
434# to be cyclic. Threads are not allowed into it until it has fully drained
435# since the previous cycle. In addition, a 'resetting' state exists which is
436# similar to 'draining' except that threads leave with a BrokenBarrierError,
437# and a 'broken' state in which all threads get get the exception.
438class Barrier(_Verbose):
439 """
440 Barrier. Useful for synchronizing a fixed number of threads
441 at known synchronization points. Threads block on 'wait()' and are
442 simultaneously once they have all made that call.
443 """
444 def __init__(self, parties, action=None, timeout=None, verbose=None):
445 """
446 Create a barrier, initialised to 'parties' threads.
447 'action' is a callable which, when supplied, will be called
448 by one of the threads after they have all entered the
449 barrier and just prior to releasing them all.
450 If a 'timeout' is provided, it is uses as the default for
451 all subsequent 'wait()' calls.
452 """
453 _Verbose.__init__(self, verbose)
454 self._cond = Condition(Lock())
455 self._action = action
456 self._timeout = timeout
457 self._parties = parties
458 self._state = 0 #0 filling, 1, draining, -1 resetting, -2 broken
459 self._count = 0
460
461 def wait(self, timeout=None):
462 """
463 Wait for the barrier. When the specified number of threads have
464 started waiting, they are all simultaneously awoken. If an 'action'
465 was provided for the barrier, one of the threads will have executed
466 that callback prior to returning.
467 Returns an individual index number from 0 to 'parties-1'.
468 """
469 if timeout is None:
470 timeout = self._timeout
471 with self._cond:
472 self._enter() # Block while the barrier drains.
473 index = self._count
474 self._count += 1
475 try:
476 if index + 1 == self._parties:
477 # We release the barrier
478 self._release()
479 else:
480 # We wait until someone releases us
481 self._wait(timeout)
482 return index
483 finally:
484 self._count -= 1
485 # Wake up any threads waiting for barrier to drain.
486 self._exit()
487
488 # Block until the barrier is ready for us, or raise an exception
489 # if it is broken.
490 def _enter(self):
491 while self._state in (-1, 1):
492 # It is draining or resetting, wait until done
493 self._cond.wait()
494 #see if the barrier is in a broken state
495 if self._state < 0:
496 raise BrokenBarrierError
497 assert self._state == 0
498
499 # Optionally run the 'action' and release the threads waiting
500 # in the barrier.
501 def _release(self):
502 try:
503 if self._action:
504 self._action()
505 # enter draining state
506 self._state = 1
507 self._cond.notify_all()
508 except:
509 #an exception during the _action handler. Break and reraise
510 self._break()
511 raise
512
513 # Wait in the barrier until we are relased. Raise an exception
514 # if the barrier is reset or broken.
515 def _wait(self, timeout):
Kristján Valur Jónsson63315202010-11-18 12:46:39 +0000516 if not self._cond.wait_for(lambda : self._state != 0, timeout):
517 #timed out. Break the barrier
518 self._break()
519 raise BrokenBarrierError
520 if self._state < 0:
521 raise BrokenBarrierError
Kristján Valur Jónsson3be00032010-10-28 09:43:10 +0000522 assert self._state == 1
523
524 # If we are the last thread to exit the barrier, signal any threads
525 # waiting for the barrier to drain.
526 def _exit(self):
527 if self._count == 0:
528 if self._state in (-1, 1):
529 #resetting or draining
530 self._state = 0
531 self._cond.notify_all()
532
533 def reset(self):
534 """
535 Reset the barrier to the initial state.
536 Any threads currently waiting will get the BrokenBarrier exception
537 raised.
538 """
539 with self._cond:
540 if self._count > 0:
541 if self._state == 0:
542 #reset the barrier, waking up threads
543 self._state = -1
544 elif self._state == -2:
545 #was broken, set it to reset state
546 #which clears when the last thread exits
547 self._state = -1
548 else:
549 self._state = 0
550 self._cond.notify_all()
551
552 def abort(self):
553 """
554 Place the barrier into a 'broken' state.
555 Useful in case of error. Any currently waiting threads and
556 threads attempting to 'wait()' will have BrokenBarrierError
557 raised.
558 """
559 with self._cond:
560 self._break()
561
562 def _break(self):
563 # An internal error was detected. The barrier is set to
564 # a broken state all parties awakened.
565 self._state = -2
566 self._cond.notify_all()
567
568 @property
569 def parties(self):
570 """
571 Return the number of threads required to trip the barrier.
572 """
573 return self._parties
574
575 @property
576 def n_waiting(self):
577 """
578 Return the number of threads that are currently waiting at the barrier.
579 """
580 # We don't need synchronization here since this is an ephemeral result
581 # anyway. It returns the correct value in the steady state.
582 if self._state == 0:
583 return self._count
584 return 0
585
586 @property
587 def broken(self):
588 """
589 Return True if the barrier is in a broken state
590 """
591 return self._state == -2
592
593#exception raised by the Barrier class
594class BrokenBarrierError(RuntimeError): pass
595
596
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000597# Helper to generate new thread names
598_counter = 0
599def _newname(template="Thread-%d"):
600 global _counter
601 _counter = _counter + 1
602 return template % _counter
603
604# Active thread administration
605_active_limbo_lock = _allocate_lock()
Tim Peters711906e2005-01-08 07:30:42 +0000606_active = {} # maps thread id to Thread object
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000607_limbo = {}
608
609
610# Main class for threads
611
612class Thread(_Verbose):
613
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000614 __initialized = False
Brett Cannoncc4e9352004-07-03 03:52:35 +0000615 # Need to store a reference to sys.exc_info for printing
616 # out exceptions when a thread tries to use a global var. during interp.
617 # shutdown and thus raises an exception about trying to perform some
618 # operation on/with a NoneType
619 __exc_info = _sys.exc_info
Christian Heimesbbe741d2008-03-28 10:53:29 +0000620 # Keep sys.exc_clear too to clear the exception just before
621 # allowing .join() to return.
622 #XXX __exc_clear = _sys.exc_clear
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000623
624 def __init__(self, group=None, target=None, name=None,
Antoine Pitrou0bd4deb2011-02-25 22:07:43 +0000625 args=(), kwargs=None, verbose=None, *, daemon=None):
Guido van Rossum5a43e1a1998-06-09 19:04:26 +0000626 assert group is None, "group argument must be None for now"
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000627 _Verbose.__init__(self, verbose)
Georg Brandla4a8b822005-07-15 09:13:21 +0000628 if kwargs is None:
629 kwargs = {}
Guido van Rossumd0648992007-08-20 19:25:41 +0000630 self._target = target
631 self._name = str(name or _newname())
632 self._args = args
633 self._kwargs = kwargs
Antoine Pitrou0bd4deb2011-02-25 22:07:43 +0000634 if daemon is not None:
635 self._daemonic = daemon
636 else:
637 self._daemonic = current_thread().daemon
Georg Brandl0c77a822008-06-10 16:37:50 +0000638 self._ident = None
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000639 self._started = Event()
Guido van Rossumd0648992007-08-20 19:25:41 +0000640 self._stopped = False
641 self._block = Condition(Lock())
642 self._initialized = True
Brett Cannoncc4e9352004-07-03 03:52:35 +0000643 # sys.stderr is not stored in the class like
644 # sys.exc_info since it can be changed between instances
Guido van Rossumd0648992007-08-20 19:25:41 +0000645 self._stderr = _sys.stderr
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000646
Gregory P. Smith9bd4a242011-01-04 18:33:38 +0000647 def _reset_internal_locks(self):
648 # private! Called by _after_fork() to reset our internal locks as
649 # they may be in an invalid state leading to a deadlock or crash.
650 if hasattr(self, '_block'): # DummyThread deletes _block
651 self._block.__init__()
652 self._started._reset_internal_locks()
653
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000654 def __repr__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000655 assert self._initialized, "Thread.__init__() was not called"
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000656 status = "initial"
Benjamin Peterson672b8032008-06-11 19:14:14 +0000657 if self._started.is_set():
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000658 status = "started"
Guido van Rossumd0648992007-08-20 19:25:41 +0000659 if self._stopped:
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000660 status = "stopped"
Guido van Rossumd0648992007-08-20 19:25:41 +0000661 if self._daemonic:
Georg Brandl0c77a822008-06-10 16:37:50 +0000662 status += " daemon"
663 if self._ident is not None:
664 status += " %s" % self._ident
Guido van Rossumd0648992007-08-20 19:25:41 +0000665 return "<%s(%s, %s)>" % (self.__class__.__name__, self._name, status)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000666
667 def start(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000668 if not self._initialized:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000669 raise RuntimeError("thread.__init__() not called")
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000670
Benjamin Peterson672b8032008-06-11 19:14:14 +0000671 if self._started.is_set():
Senthil Kumaranfdd4d0f2010-04-06 03:30:18 +0000672 raise RuntimeError("threads can only be started once")
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000673 if __debug__:
674 self._note("%s.start(): starting thread", self)
Benjamin Petersond23f8222009-04-05 19:13:16 +0000675 with _active_limbo_lock:
676 _limbo[self] = self
Gregory P. Smith3fdd9642010-02-28 18:57:46 +0000677 try:
678 _start_new_thread(self._bootstrap, ())
679 except Exception:
680 with _active_limbo_lock:
681 del _limbo[self]
682 raise
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000683 self._started.wait()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000684
685 def run(self):
Christian Heimesd3eb5a152008-02-24 00:38:49 +0000686 try:
687 if self._target:
688 self._target(*self._args, **self._kwargs)
689 finally:
690 # Avoid a refcycle if the thread is running a function with
691 # an argument that has a member that points to the thread.
692 del self._target, self._args, self._kwargs
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000693
Guido van Rossumd0648992007-08-20 19:25:41 +0000694 def _bootstrap(self):
Guido van Rossum61e21b52007-08-20 19:06:03 +0000695 # Wrapper around the real bootstrap code that ignores
696 # exceptions during interpreter cleanup. Those typically
697 # happen when a daemon thread wakes up at an unfortunate
698 # moment, finds the world around it destroyed, and raises some
699 # random exception *** while trying to report the exception in
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000700 # _bootstrap_inner() below ***. Those random exceptions
Guido van Rossum61e21b52007-08-20 19:06:03 +0000701 # don't help anybody, and they confuse users, so we suppress
702 # them. We suppress them only when it appears that the world
703 # indeed has already been destroyed, so that exceptions in
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000704 # _bootstrap_inner() during normal business hours are properly
Guido van Rossum61e21b52007-08-20 19:06:03 +0000705 # reported. Also, we only suppress them for daemonic threads;
706 # if a non-daemonic encounters this, something else is wrong.
707 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000708 self._bootstrap_inner()
Guido van Rossum61e21b52007-08-20 19:06:03 +0000709 except:
Guido van Rossumd0648992007-08-20 19:25:41 +0000710 if self._daemonic and _sys is None:
Guido van Rossum61e21b52007-08-20 19:06:03 +0000711 return
712 raise
713
Benjamin Petersond23f8222009-04-05 19:13:16 +0000714 def _set_ident(self):
715 self._ident = _get_ident()
716
Guido van Rossumd0648992007-08-20 19:25:41 +0000717 def _bootstrap_inner(self):
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000718 try:
Benjamin Petersond23f8222009-04-05 19:13:16 +0000719 self._set_ident()
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000720 self._started.set()
Benjamin Petersond23f8222009-04-05 19:13:16 +0000721 with _active_limbo_lock:
722 _active[self._ident] = self
723 del _limbo[self]
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000724 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000725 self._note("%s._bootstrap(): thread started", self)
Jeremy Hyltonbfccb352003-06-29 16:58:41 +0000726
727 if _trace_hook:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000728 self._note("%s._bootstrap(): registering trace hook", self)
Jeremy Hyltonbfccb352003-06-29 16:58:41 +0000729 _sys.settrace(_trace_hook)
730 if _profile_hook:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000731 self._note("%s._bootstrap(): registering profile hook", self)
Jeremy Hyltonbfccb352003-06-29 16:58:41 +0000732 _sys.setprofile(_profile_hook)
Tim Petersd1b108b2003-06-29 17:24:17 +0000733
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000734 try:
735 self.run()
736 except SystemExit:
737 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000738 self._note("%s._bootstrap(): raised SystemExit", self)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000739 except:
740 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000741 self._note("%s._bootstrap(): unhandled exception", self)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000742 # If sys.stderr is no more (most likely from interpreter
Guido van Rossumd0648992007-08-20 19:25:41 +0000743 # shutdown) use self._stderr. Otherwise still use sys (as in
Brett Cannoncc4e9352004-07-03 03:52:35 +0000744 # _sys) in case sys.stderr was redefined since the creation of
745 # self.
746 if _sys:
747 _sys.stderr.write("Exception in thread %s:\n%s\n" %
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000748 (self.name, _format_exc()))
Brett Cannoncc4e9352004-07-03 03:52:35 +0000749 else:
750 # Do the best job possible w/o a huge amt. of code to
751 # approximate a traceback (code ideas from
752 # Lib/traceback.py)
Guido van Rossumd0648992007-08-20 19:25:41 +0000753 exc_type, exc_value, exc_tb = self._exc_info()
Brett Cannoncc4e9352004-07-03 03:52:35 +0000754 try:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000755 print((
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000756 "Exception in thread " + self.name +
Guido van Rossumd0648992007-08-20 19:25:41 +0000757 " (most likely raised during interpreter shutdown):"), file=self._stderr)
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000758 print((
Guido van Rossumd0648992007-08-20 19:25:41 +0000759 "Traceback (most recent call last):"), file=self._stderr)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000760 while exc_tb:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000761 print((
Brett Cannoncc4e9352004-07-03 03:52:35 +0000762 ' File "%s", line %s, in %s' %
763 (exc_tb.tb_frame.f_code.co_filename,
764 exc_tb.tb_lineno,
Guido van Rossumd0648992007-08-20 19:25:41 +0000765 exc_tb.tb_frame.f_code.co_name)), file=self._stderr)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000766 exc_tb = exc_tb.tb_next
Guido van Rossumd0648992007-08-20 19:25:41 +0000767 print(("%s: %s" % (exc_type, exc_value)), file=self._stderr)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000768 # Make sure that exc_tb gets deleted since it is a memory
769 # hog; deleting everything else is just for thoroughness
770 finally:
771 del exc_type, exc_value, exc_tb
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000772 else:
773 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000774 self._note("%s._bootstrap(): normal return", self)
Christian Heimesbbe741d2008-03-28 10:53:29 +0000775 finally:
776 # Prevent a race in
777 # test_threading.test_no_refcycle_through_target when
778 # the exception keeps the target alive past when we
779 # assert that it's dead.
780 #XXX self.__exc_clear()
781 pass
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000782 finally:
Christian Heimes1af737c2008-01-23 08:24:23 +0000783 with _active_limbo_lock:
784 self._stop()
785 try:
Georg Brandl0c77a822008-06-10 16:37:50 +0000786 # We don't call self._delete() because it also
Christian Heimes1af737c2008-01-23 08:24:23 +0000787 # grabs _active_limbo_lock.
788 del _active[_get_ident()]
789 except:
790 pass
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000791
Guido van Rossumd0648992007-08-20 19:25:41 +0000792 def _stop(self):
Christian Heimes969fe572008-01-25 11:23:10 +0000793 self._block.acquire()
794 self._stopped = True
Benjamin Peterson672b8032008-06-11 19:14:14 +0000795 self._block.notify_all()
Christian Heimes969fe572008-01-25 11:23:10 +0000796 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000797
Guido van Rossumd0648992007-08-20 19:25:41 +0000798 def _delete(self):
Tim Peters21429932004-07-21 03:36:52 +0000799 "Remove current thread from the dict of currently running threads."
Brett Cannon8b3d92a2004-07-21 02:21:58 +0000800
Georg Brandl2067bfd2008-05-25 13:05:15 +0000801 # Notes about running with _dummy_thread:
Tim Peters21429932004-07-21 03:36:52 +0000802 #
Georg Brandl2067bfd2008-05-25 13:05:15 +0000803 # Must take care to not raise an exception if _dummy_thread is being
Tim Peters21429932004-07-21 03:36:52 +0000804 # used (and thus this module is being used as an instance of
Georg Brandl2067bfd2008-05-25 13:05:15 +0000805 # dummy_threading). _dummy_thread.get_ident() always returns -1 since
806 # there is only one thread if _dummy_thread is being used. Thus
Tim Peters21429932004-07-21 03:36:52 +0000807 # len(_active) is always <= 1 here, and any Thread instance created
808 # overwrites the (if any) thread currently registered in _active.
809 #
810 # An instance of _MainThread is always created by 'threading'. This
811 # gets overwritten the instant an instance of Thread is created; both
Georg Brandl2067bfd2008-05-25 13:05:15 +0000812 # threads return -1 from _dummy_thread.get_ident() and thus have the
Tim Peters21429932004-07-21 03:36:52 +0000813 # same key in the dict. So when the _MainThread instance created by
814 # 'threading' tries to clean itself up when atexit calls this method
815 # it gets a KeyError if another Thread instance was created.
816 #
817 # This all means that KeyError from trying to delete something from
818 # _active if dummy_threading is being used is a red herring. But
819 # since it isn't if dummy_threading is *not* being used then don't
820 # hide the exception.
Brett Cannon8b3d92a2004-07-21 02:21:58 +0000821
Christian Heimes969fe572008-01-25 11:23:10 +0000822 try:
Neal Norwitzf5c7c2e2008-04-05 04:47:45 +0000823 with _active_limbo_lock:
Brett Cannon8b3d92a2004-07-21 02:21:58 +0000824 del _active[_get_ident()]
Neal Norwitzf5c7c2e2008-04-05 04:47:45 +0000825 # There must not be any python code between the previous line
826 # and after the lock is released. Otherwise a tracing function
827 # could try to acquire the lock again in the same thread, (in
Benjamin Peterson672b8032008-06-11 19:14:14 +0000828 # current_thread()), and would block.
Neal Norwitzf5c7c2e2008-04-05 04:47:45 +0000829 except KeyError:
830 if 'dummy_threading' not in _sys.modules:
831 raise
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000832
833 def join(self, timeout=None):
Guido van Rossumd0648992007-08-20 19:25:41 +0000834 if not self._initialized:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000835 raise RuntimeError("Thread.__init__() not called")
Benjamin Peterson672b8032008-06-11 19:14:14 +0000836 if not self._started.is_set():
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000837 raise RuntimeError("cannot join thread before it is started")
Benjamin Peterson672b8032008-06-11 19:14:14 +0000838 if self is current_thread():
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000839 raise RuntimeError("cannot join current thread")
840
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000841 if __debug__:
Guido van Rossumd0648992007-08-20 19:25:41 +0000842 if not self._stopped:
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000843 self._note("%s.join(): waiting until thread stops", self)
Christian Heimes969fe572008-01-25 11:23:10 +0000844
845 self._block.acquire()
846 try:
Brett Cannonad07ff22005-11-23 02:15:50 +0000847 if timeout is None:
Guido van Rossumd0648992007-08-20 19:25:41 +0000848 while not self._stopped:
849 self._block.wait()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000850 if __debug__:
851 self._note("%s.join(): thread stopped", self)
Brett Cannonad07ff22005-11-23 02:15:50 +0000852 else:
853 deadline = _time() + timeout
Guido van Rossumd0648992007-08-20 19:25:41 +0000854 while not self._stopped:
Brett Cannonad07ff22005-11-23 02:15:50 +0000855 delay = deadline - _time()
856 if delay <= 0:
857 if __debug__:
858 self._note("%s.join(): timed out", self)
859 break
Guido van Rossumd0648992007-08-20 19:25:41 +0000860 self._block.wait(delay)
Brett Cannonad07ff22005-11-23 02:15:50 +0000861 else:
862 if __debug__:
863 self._note("%s.join(): thread stopped", self)
Christian Heimes969fe572008-01-25 11:23:10 +0000864 finally:
865 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000866
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000867 @property
868 def name(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000869 assert self._initialized, "Thread.__init__() not called"
870 return self._name
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000871
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000872 @name.setter
873 def name(self, name):
Guido van Rossumd0648992007-08-20 19:25:41 +0000874 assert self._initialized, "Thread.__init__() not called"
875 self._name = str(name)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000876
Benjamin Peterson773c17b2008-08-18 16:45:31 +0000877 @property
878 def ident(self):
Georg Brandl0c77a822008-06-10 16:37:50 +0000879 assert self._initialized, "Thread.__init__() not called"
880 return self._ident
881
Benjamin Peterson672b8032008-06-11 19:14:14 +0000882 def is_alive(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000883 assert self._initialized, "Thread.__init__() not called"
Benjamin Peterson672b8032008-06-11 19:14:14 +0000884 return self._started.is_set() and not self._stopped
Tim Petersb90f89a2001-01-15 03:26:36 +0000885
Benjamin Petersonb3085c92008-09-01 23:09:31 +0000886 isAlive = is_alive
Benjamin Petersonf0923f52008-08-18 22:10:13 +0000887
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000888 @property
889 def daemon(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000890 assert self._initialized, "Thread.__init__() not called"
891 return self._daemonic
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000892
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000893 @daemon.setter
894 def daemon(self, daemonic):
Guido van Rossumd0648992007-08-20 19:25:41 +0000895 if not self._initialized:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000896 raise RuntimeError("Thread.__init__() not called")
Benjamin Peterson672b8032008-06-11 19:14:14 +0000897 if self._started.is_set():
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000898 raise RuntimeError("cannot set daemon status of active thread");
Guido van Rossumd0648992007-08-20 19:25:41 +0000899 self._daemonic = daemonic
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000900
Benjamin Peterson6640d722008-08-18 18:16:46 +0000901 def isDaemon(self):
902 return self.daemon
903
904 def setDaemon(self, daemonic):
905 self.daemon = daemonic
906
907 def getName(self):
908 return self.name
909
910 def setName(self, name):
911 self.name = name
912
Martin v. Löwis44f86962001-09-05 13:44:54 +0000913# The timer class was contributed by Itamar Shtull-Trauring
914
915def Timer(*args, **kwargs):
916 return _Timer(*args, **kwargs)
917
918class _Timer(Thread):
919 """Call a function after a specified number of seconds:
Tim Petersb64bec32001-09-18 02:26:39 +0000920
Martin v. Löwis44f86962001-09-05 13:44:54 +0000921 t = Timer(30.0, f, args=[], kwargs={})
922 t.start()
923 t.cancel() # stop the timer's action if it's still waiting
924 """
Tim Petersb64bec32001-09-18 02:26:39 +0000925
Martin v. Löwis44f86962001-09-05 13:44:54 +0000926 def __init__(self, interval, function, args=[], kwargs={}):
927 Thread.__init__(self)
928 self.interval = interval
929 self.function = function
930 self.args = args
931 self.kwargs = kwargs
932 self.finished = Event()
Tim Petersb64bec32001-09-18 02:26:39 +0000933
Martin v. Löwis44f86962001-09-05 13:44:54 +0000934 def cancel(self):
935 """Stop the timer if it hasn't finished yet"""
936 self.finished.set()
Tim Petersb64bec32001-09-18 02:26:39 +0000937
Martin v. Löwis44f86962001-09-05 13:44:54 +0000938 def run(self):
939 self.finished.wait(self.interval)
Benjamin Peterson672b8032008-06-11 19:14:14 +0000940 if not self.finished.is_set():
Martin v. Löwis44f86962001-09-05 13:44:54 +0000941 self.function(*self.args, **self.kwargs)
942 self.finished.set()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000943
944# Special thread class to represent the main thread
945# This is garbage collected through an exit handler
946
947class _MainThread(Thread):
948
949 def __init__(self):
Antoine Pitrou0bd4deb2011-02-25 22:07:43 +0000950 Thread.__init__(self, name="MainThread", daemon=False)
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000951 self._started.set()
Benjamin Petersond23f8222009-04-05 19:13:16 +0000952 self._set_ident()
953 with _active_limbo_lock:
954 _active[self._ident] = self
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000955
Thomas Wouters902d6eb2007-01-09 23:18:33 +0000956 def _exitfunc(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000957 self._stop()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000958 t = _pickSomeNonDaemonThread()
959 if t:
960 if __debug__:
961 self._note("%s: waiting for other threads", self)
962 while t:
963 t.join()
964 t = _pickSomeNonDaemonThread()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000965 if __debug__:
966 self._note("%s: exiting", self)
Guido van Rossumd0648992007-08-20 19:25:41 +0000967 self._delete()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000968
969def _pickSomeNonDaemonThread():
970 for t in enumerate():
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000971 if not t.daemon and t.is_alive():
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000972 return t
973 return None
974
975
976# Dummy thread class to represent threads not started here.
Tim Peters711906e2005-01-08 07:30:42 +0000977# These aren't garbage collected when they die, nor can they be waited for.
Benjamin Peterson672b8032008-06-11 19:14:14 +0000978# If they invoke anything in threading.py that calls current_thread(), they
Tim Peters711906e2005-01-08 07:30:42 +0000979# leave an entry in the _active dict forever after.
Benjamin Peterson672b8032008-06-11 19:14:14 +0000980# Their purpose is to return *something* from current_thread().
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000981# They are marked as daemon threads so we won't wait for them
982# when we exit (conform previous semantics).
983
984class _DummyThread(Thread):
Tim Petersb90f89a2001-01-15 03:26:36 +0000985
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000986 def __init__(self):
Antoine Pitrou0bd4deb2011-02-25 22:07:43 +0000987 Thread.__init__(self, name=_newname("Dummy-%d"), daemon=True)
Tim Peters711906e2005-01-08 07:30:42 +0000988
Gregory P. Smith9bd4a242011-01-04 18:33:38 +0000989 # Thread._block consumes an OS-level locking primitive, which
Tim Peters711906e2005-01-08 07:30:42 +0000990 # can never be used by a _DummyThread. Since a _DummyThread
991 # instance is immortal, that's bad, so release this resource.
Guido van Rossumd0648992007-08-20 19:25:41 +0000992 del self._block
Tim Peters711906e2005-01-08 07:30:42 +0000993
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000994 self._started.set()
Benjamin Petersond23f8222009-04-05 19:13:16 +0000995 self._set_ident()
996 with _active_limbo_lock:
997 _active[self._ident] = self
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000998
Neal Norwitz45bec8c2002-02-19 03:01:36 +0000999 def join(self, timeout=None):
Guido van Rossum8ca162f2002-04-07 06:36:23 +00001000 assert False, "cannot join a dummy thread"
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001001
1002
1003# Global API functions
1004
Benjamin Peterson672b8032008-06-11 19:14:14 +00001005def current_thread():
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001006 try:
1007 return _active[_get_ident()]
1008 except KeyError:
Benjamin Peterson672b8032008-06-11 19:14:14 +00001009 ##print "current_thread(): no current thread for", _get_ident()
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001010 return _DummyThread()
1011
Benjamin Petersonb3085c92008-09-01 23:09:31 +00001012currentThread = current_thread
Benjamin Petersonf0923f52008-08-18 22:10:13 +00001013
Benjamin Peterson672b8032008-06-11 19:14:14 +00001014def active_count():
Benjamin Petersond23f8222009-04-05 19:13:16 +00001015 with _active_limbo_lock:
1016 return len(_active) + len(_limbo)
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001017
Benjamin Petersonb3085c92008-09-01 23:09:31 +00001018activeCount = active_count
Benjamin Petersonf0923f52008-08-18 22:10:13 +00001019
Antoine Pitroubdec11f2009-11-05 13:49:14 +00001020def _enumerate():
1021 # Same as enumerate(), but without the lock. Internal use only.
1022 return list(_active.values()) + list(_limbo.values())
1023
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001024def enumerate():
Benjamin Petersond23f8222009-04-05 19:13:16 +00001025 with _active_limbo_lock:
1026 return list(_active.values()) + list(_limbo.values())
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001027
Georg Brandl2067bfd2008-05-25 13:05:15 +00001028from _thread import stack_size
Thomas Wouters0e3f5912006-08-11 14:57:12 +00001029
Thomas Wouters902d6eb2007-01-09 23:18:33 +00001030# Create the main thread object,
1031# and make it available for the interpreter
1032# (Py_Main) as threading._shutdown.
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001033
Thomas Wouters902d6eb2007-01-09 23:18:33 +00001034_shutdown = _MainThread()._exitfunc
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001035
Jim Fultond15dc062004-07-14 19:11:50 +00001036# get thread-local implementation, either from the thread
1037# module, or from the python fallback
1038
1039try:
Georg Brandl2067bfd2008-05-25 13:05:15 +00001040 from _thread import _local as local
Jim Fultond15dc062004-07-14 19:11:50 +00001041except ImportError:
1042 from _threading_local import local
1043
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001044
Jesse Nollera8513972008-07-17 16:49:17 +00001045def _after_fork():
1046 # This function is called by Python/ceval.c:PyEval_ReInitThreads which
1047 # is called from PyOS_AfterFork. Here we cleanup threading module state
1048 # that should not exist after a fork.
1049
1050 # Reset _active_limbo_lock, in case we forked while the lock was held
1051 # by another (non-forked) thread. http://bugs.python.org/issue874900
1052 global _active_limbo_lock
1053 _active_limbo_lock = _allocate_lock()
1054
1055 # fork() only copied the current thread; clear references to others.
1056 new_active = {}
1057 current = current_thread()
1058 with _active_limbo_lock:
Antoine Pitrou5fe291f2008-09-06 23:00:03 +00001059 for thread in _active.values():
Jesse Nollera8513972008-07-17 16:49:17 +00001060 if thread is current:
Antoine Pitrou5fe291f2008-09-06 23:00:03 +00001061 # There is only one active thread. We reset the ident to
1062 # its new value since it can have changed.
1063 ident = _get_ident()
1064 thread._ident = ident
Gregory P. Smith96c886c2011-01-03 21:06:12 +00001065 # Any condition variables hanging off of the active thread may
1066 # be in an invalid state, so we reinitialize them.
Gregory P. Smith9bd4a242011-01-04 18:33:38 +00001067 thread._reset_internal_locks()
Jesse Nollera8513972008-07-17 16:49:17 +00001068 new_active[ident] = thread
1069 else:
1070 # All the others are already stopped.
1071 # We don't call _Thread__stop() because it tries to acquire
1072 # thread._Thread__block which could also have been held while
1073 # we forked.
Antoine Pitrou5fe291f2008-09-06 23:00:03 +00001074 thread._stopped = True
Jesse Nollera8513972008-07-17 16:49:17 +00001075
1076 _limbo.clear()
1077 _active.clear()
1078 _active.update(new_active)
1079 assert len(_active) == 1