blob: d2609834527adeb1f41f8d82fae70c35c5914b5c [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
Antoine Pitrouc081c0c2011-07-15 22:12:24 +02009from _weakrefset import WeakSet
Guido van Rossum7f5013a1998-04-09 22:01:42 +000010
Benjamin Petersonb3085c92008-09-01 23:09:31 +000011# Note regarding PEP 8 compliant names
12# This threading model was originally inspired by Java, and inherited
13# the convention of camelCase function and method names from that
14# language. Those originaly names are not in any imminent danger of
15# being deprecated (even for Py3k),so this module provides them as an
16# alias for the PEP 8 compliant names
17# Note that using the new PEP 8 compliant names facilitates substitution
18# with the multiprocessing module, which doesn't provide the old
19# Java inspired names.
20
Benjamin Peterson672b8032008-06-11 19:14:14 +000021__all__ = ['active_count', 'Condition', 'current_thread', 'enumerate', 'Event',
Raymond Hettinger5cee47f2011-01-11 19:59:46 +000022 'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Thread', 'Barrier',
Thomas Wouters0e3f5912006-08-11 14:57:12 +000023 'Timer', 'setprofile', 'settrace', 'local', 'stack_size']
Guido van Rossum7f5013a1998-04-09 22:01:42 +000024
Raymond Hettinger5cee47f2011-01-11 19:59:46 +000025# Rename some stuff so "from threading import *" is safe
Georg Brandl2067bfd2008-05-25 13:05:15 +000026_start_new_thread = _thread.start_new_thread
27_allocate_lock = _thread.allocate_lock
28_get_ident = _thread.get_ident
29ThreadError = _thread.error
Antoine Pitrou434736a2009-11-10 18:46:01 +000030try:
31 _CRLock = _thread.RLock
32except AttributeError:
33 _CRLock = None
Antoine Pitrou7c3e5772010-04-14 15:44:10 +000034TIMEOUT_MAX = _thread.TIMEOUT_MAX
Georg Brandl2067bfd2008-05-25 13:05:15 +000035del _thread
Guido van Rossum7f5013a1998-04-09 22:01:42 +000036
Guido van Rossum7f5013a1998-04-09 22:01:42 +000037
Tim Peters59aba122003-07-01 20:01:55 +000038# Debug support (adapted from ihooks.py).
Guido van Rossum7f5013a1998-04-09 22:01:42 +000039
Tim Peters0939fac2003-07-01 19:28:44 +000040_VERBOSE = False
Guido van Rossum7f5013a1998-04-09 22:01:42 +000041
42if __debug__:
43
Tim Peters59aba122003-07-01 20:01:55 +000044 class _Verbose(object):
Guido van Rossum7f5013a1998-04-09 22:01:42 +000045
46 def __init__(self, verbose=None):
47 if verbose is None:
48 verbose = _VERBOSE
Guido van Rossumd0648992007-08-20 19:25:41 +000049 self._verbose = verbose
Guido van Rossum7f5013a1998-04-09 22:01:42 +000050
51 def _note(self, format, *args):
Guido van Rossumd0648992007-08-20 19:25:41 +000052 if self._verbose:
Guido van Rossum7f5013a1998-04-09 22:01:42 +000053 format = format % args
Antoine Pitrou401edd62010-12-17 17:42:16 +000054 # Issue #4188: calling current_thread() can incur an infinite
55 # recursion if it has to create a DummyThread on the fly.
56 ident = _get_ident()
57 try:
58 name = _active[ident].name
59 except KeyError:
60 name = "<OS thread %d>" % ident
61 format = "%s: %s\n" % (name, format)
Guido van Rossum7f5013a1998-04-09 22:01:42 +000062 _sys.stderr.write(format)
63
64else:
65 # Disable this when using "python -O"
Tim Peters59aba122003-07-01 20:01:55 +000066 class _Verbose(object):
Guido van Rossum7f5013a1998-04-09 22:01:42 +000067 def __init__(self, verbose=None):
68 pass
69 def _note(self, *args):
70 pass
71
Jeremy Hyltonbfccb352003-06-29 16:58:41 +000072# Support for profile and trace hooks
73
74_profile_hook = None
75_trace_hook = None
76
77def setprofile(func):
78 global _profile_hook
79 _profile_hook = func
Tim Petersd1b108b2003-06-29 17:24:17 +000080
Jeremy Hyltonbfccb352003-06-29 16:58:41 +000081def settrace(func):
82 global _trace_hook
83 _trace_hook = func
Guido van Rossum7f5013a1998-04-09 22:01:42 +000084
85# Synchronization classes
86
87Lock = _allocate_lock
88
Antoine Pitrou434736a2009-11-10 18:46:01 +000089def RLock(verbose=None, *args, **kwargs):
90 if verbose is None:
91 verbose = _VERBOSE
92 if (__debug__ and verbose) or _CRLock is None:
93 return _PyRLock(verbose, *args, **kwargs)
94 return _CRLock(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +000095
96class _RLock(_Verbose):
Tim Petersb90f89a2001-01-15 03:26:36 +000097
Guido van Rossum7f5013a1998-04-09 22:01:42 +000098 def __init__(self, verbose=None):
99 _Verbose.__init__(self, verbose)
Guido van Rossumd0648992007-08-20 19:25:41 +0000100 self._block = _allocate_lock()
101 self._owner = None
102 self._count = 0
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000103
104 def __repr__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000105 owner = self._owner
Antoine Pitroub0872682009-11-09 16:08:16 +0000106 try:
107 owner = _active[owner].name
108 except KeyError:
109 pass
110 return "<%s owner=%r count=%d>" % (
111 self.__class__.__name__, owner, self._count)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000112
Antoine Pitrou7c3e5772010-04-14 15:44:10 +0000113 def acquire(self, blocking=True, timeout=-1):
Antoine Pitroub0872682009-11-09 16:08:16 +0000114 me = _get_ident()
115 if self._owner == me:
Guido van Rossumd0648992007-08-20 19:25:41 +0000116 self._count = self._count + 1
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000117 if __debug__:
118 self._note("%s.acquire(%s): recursive success", self, blocking)
119 return 1
Antoine Pitrou7c3e5772010-04-14 15:44:10 +0000120 rc = self._block.acquire(blocking, timeout)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000121 if rc:
Guido van Rossumd0648992007-08-20 19:25:41 +0000122 self._owner = me
123 self._count = 1
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000124 if __debug__:
Brett Cannon90cece72005-01-27 22:48:30 +0000125 self._note("%s.acquire(%s): initial success", self, blocking)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000126 else:
127 if __debug__:
128 self._note("%s.acquire(%s): failure", self, blocking)
129 return rc
130
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000131 __enter__ = acquire
132
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000133 def release(self):
Antoine Pitroub0872682009-11-09 16:08:16 +0000134 if self._owner != _get_ident():
Georg Brandl495f7b52009-10-27 15:28:25 +0000135 raise RuntimeError("cannot release un-acquired lock")
Guido van Rossumd0648992007-08-20 19:25:41 +0000136 self._count = count = self._count - 1
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000137 if not count:
Guido van Rossumd0648992007-08-20 19:25:41 +0000138 self._owner = None
139 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000140 if __debug__:
141 self._note("%s.release(): final release", self)
142 else:
143 if __debug__:
144 self._note("%s.release(): non-final release", self)
145
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000146 def __exit__(self, t, v, tb):
147 self.release()
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000148
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000149 # Internal methods used by condition variables
150
Guido van Rossum1bc535d2007-05-15 18:46:22 +0000151 def _acquire_restore(self, state):
Guido van Rossumd0648992007-08-20 19:25:41 +0000152 self._block.acquire()
153 self._count, self._owner = state
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000154 if __debug__:
155 self._note("%s._acquire_restore()", self)
156
157 def _release_save(self):
158 if __debug__:
159 self._note("%s._release_save()", self)
Guido van Rossumd0648992007-08-20 19:25:41 +0000160 count = self._count
161 self._count = 0
162 owner = self._owner
163 self._owner = None
164 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000165 return (count, owner)
166
167 def _is_owned(self):
Antoine Pitroub0872682009-11-09 16:08:16 +0000168 return self._owner == _get_ident()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000169
Antoine Pitrou434736a2009-11-10 18:46:01 +0000170_PyRLock = _RLock
171
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000172
173def Condition(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000174 return _Condition(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000175
176class _Condition(_Verbose):
177
178 def __init__(self, lock=None, verbose=None):
179 _Verbose.__init__(self, verbose)
180 if lock is None:
181 lock = RLock()
Guido van Rossumd0648992007-08-20 19:25:41 +0000182 self._lock = lock
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000183 # Export the lock's acquire() and release() methods
184 self.acquire = lock.acquire
185 self.release = lock.release
186 # If the lock defines _release_save() and/or _acquire_restore(),
187 # these override the default implementations (which just call
188 # release() and acquire() on the lock). Ditto for _is_owned().
189 try:
190 self._release_save = lock._release_save
191 except AttributeError:
192 pass
193 try:
194 self._acquire_restore = lock._acquire_restore
195 except AttributeError:
196 pass
197 try:
198 self._is_owned = lock._is_owned
199 except AttributeError:
200 pass
Guido van Rossumd0648992007-08-20 19:25:41 +0000201 self._waiters = []
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000202
Thomas Wouters477c8d52006-05-27 19:21:47 +0000203 def __enter__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000204 return self._lock.__enter__()
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000205
Thomas Wouters477c8d52006-05-27 19:21:47 +0000206 def __exit__(self, *args):
Guido van Rossumd0648992007-08-20 19:25:41 +0000207 return self._lock.__exit__(*args)
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000208
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000209 def __repr__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000210 return "<Condition(%s, %d)>" % (self._lock, len(self._waiters))
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000211
212 def _release_save(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000213 self._lock.release() # No state to save
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000214
215 def _acquire_restore(self, x):
Guido van Rossumd0648992007-08-20 19:25:41 +0000216 self._lock.acquire() # Ignore saved state
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000217
218 def _is_owned(self):
Benjamin Peterson672b8032008-06-11 19:14:14 +0000219 # Return True if lock is owned by current_thread.
Jeremy Hyltonaf7fde72002-08-14 17:43:59 +0000220 # This method is called only if __lock doesn't have _is_owned().
Guido van Rossumd0648992007-08-20 19:25:41 +0000221 if self._lock.acquire(0):
222 self._lock.release()
Tim Petersbc0e9102002-04-04 22:55:58 +0000223 return False
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000224 else:
Tim Petersbc0e9102002-04-04 22:55:58 +0000225 return True
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000226
227 def wait(self, timeout=None):
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000228 if not self._is_owned():
Georg Brandl495f7b52009-10-27 15:28:25 +0000229 raise RuntimeError("cannot wait on un-acquired lock")
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000230 waiter = _allocate_lock()
231 waiter.acquire()
Guido van Rossumd0648992007-08-20 19:25:41 +0000232 self._waiters.append(waiter)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000233 saved_state = self._release_save()
Tim Petersc951bf92001-04-02 20:15:57 +0000234 try: # restore state no matter what (e.g., KeyboardInterrupt)
235 if timeout is None:
236 waiter.acquire()
Georg Brandlb9a43912010-10-28 09:03:20 +0000237 gotit = True
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000238 if __debug__:
Tim Petersc951bf92001-04-02 20:15:57 +0000239 self._note("%s.wait(): got it", self)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000240 else:
Antoine Pitrou7c3e5772010-04-14 15:44:10 +0000241 if timeout > 0:
242 gotit = waiter.acquire(True, timeout)
243 else:
244 gotit = waiter.acquire(False)
Tim Petersc951bf92001-04-02 20:15:57 +0000245 if not gotit:
246 if __debug__:
247 self._note("%s.wait(%s): timed out", self, timeout)
248 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000249 self._waiters.remove(waiter)
Tim Petersc951bf92001-04-02 20:15:57 +0000250 except ValueError:
251 pass
252 else:
253 if __debug__:
254 self._note("%s.wait(%s): got it", self, timeout)
Georg Brandlb9a43912010-10-28 09:03:20 +0000255 return gotit
Tim Petersc951bf92001-04-02 20:15:57 +0000256 finally:
257 self._acquire_restore(saved_state)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000258
Kristján Valur Jónsson63315202010-11-18 12:46:39 +0000259 def wait_for(self, predicate, timeout=None):
260 endtime = None
261 waittime = timeout
262 result = predicate()
263 while not result:
264 if waittime is not None:
265 if endtime is None:
266 endtime = _time() + waittime
267 else:
268 waittime = endtime - _time()
269 if waittime <= 0:
270 if __debug__:
271 self._note("%s.wait_for(%r, %r): Timed out.",
272 self, predicate, timeout)
273 break
274 if __debug__:
275 self._note("%s.wait_for(%r, %r): Waiting with timeout=%s.",
276 self, predicate, timeout, waittime)
277 self.wait(waittime)
278 result = predicate()
279 else:
280 if __debug__:
281 self._note("%s.wait_for(%r, %r): Success.",
282 self, predicate, timeout)
283 return result
284
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000285 def notify(self, n=1):
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000286 if not self._is_owned():
Georg Brandl495f7b52009-10-27 15:28:25 +0000287 raise RuntimeError("cannot notify on un-acquired lock")
Guido van Rossumd0648992007-08-20 19:25:41 +0000288 __waiters = self._waiters
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000289 waiters = __waiters[:n]
290 if not waiters:
291 if __debug__:
292 self._note("%s.notify(): no waiters", self)
293 return
294 self._note("%s.notify(): notifying %d waiter%s", self, n,
295 n!=1 and "s" or "")
296 for waiter in waiters:
297 waiter.release()
298 try:
299 __waiters.remove(waiter)
300 except ValueError:
301 pass
302
Benjamin Peterson672b8032008-06-11 19:14:14 +0000303 def notify_all(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000304 self.notify(len(self._waiters))
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000305
Benjamin Petersonb3085c92008-09-01 23:09:31 +0000306 notifyAll = notify_all
307
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000308
309def Semaphore(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000310 return _Semaphore(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000311
312class _Semaphore(_Verbose):
313
Andrew M. Kuchling39d3bfc2000-02-29 00:10:24 +0000314 # After Tim Peters' semaphore class, but not quite the same (no maximum)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000315
316 def __init__(self, value=1, verbose=None):
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000317 if value < 0:
318 raise ValueError("semaphore initial value must be >= 0")
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000319 _Verbose.__init__(self, verbose)
Guido van Rossumd0648992007-08-20 19:25:41 +0000320 self._cond = Condition(Lock())
321 self._value = value
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000322
Antoine Pitrou0454af92010-04-17 23:51:58 +0000323 def acquire(self, blocking=True, timeout=None):
324 if not blocking and timeout is not None:
325 raise ValueError("can't specify timeout for non-blocking acquire")
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000326 rc = False
Antoine Pitrou0454af92010-04-17 23:51:58 +0000327 endtime = None
Guido van Rossumd0648992007-08-20 19:25:41 +0000328 self._cond.acquire()
329 while self._value == 0:
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000330 if not blocking:
331 break
Skip Montanarob446fc72001-08-19 04:25:24 +0000332 if __debug__:
333 self._note("%s.acquire(%s): blocked waiting, value=%s",
Guido van Rossumd0648992007-08-20 19:25:41 +0000334 self, blocking, self._value)
Antoine Pitrou0454af92010-04-17 23:51:58 +0000335 if timeout is not None:
336 if endtime is None:
337 endtime = _time() + timeout
338 else:
339 timeout = endtime - _time()
340 if timeout <= 0:
341 break
342 self._cond.wait(timeout)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000343 else:
Guido van Rossumd0648992007-08-20 19:25:41 +0000344 self._value = self._value - 1
Skip Montanarob446fc72001-08-19 04:25:24 +0000345 if __debug__:
Skip Montanaroae8454a2001-08-19 05:53:47 +0000346 self._note("%s.acquire: success, value=%s",
Guido van Rossumd0648992007-08-20 19:25:41 +0000347 self, self._value)
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000348 rc = True
Guido van Rossumd0648992007-08-20 19:25:41 +0000349 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000350 return rc
351
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000352 __enter__ = acquire
353
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000354 def release(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000355 self._cond.acquire()
356 self._value = self._value + 1
Skip Montanarob446fc72001-08-19 04:25:24 +0000357 if __debug__:
Skip Montanaroae8454a2001-08-19 05:53:47 +0000358 self._note("%s.release: success, value=%s",
Guido van Rossumd0648992007-08-20 19:25:41 +0000359 self, self._value)
360 self._cond.notify()
361 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000362
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000363 def __exit__(self, t, v, tb):
364 self.release()
Guido van Rossum1a5e21e2006-02-28 21:57:43 +0000365
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000366
Skip Montanaroe428bb72001-08-20 20:27:58 +0000367def BoundedSemaphore(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000368 return _BoundedSemaphore(*args, **kwargs)
Skip Montanaroe428bb72001-08-20 20:27:58 +0000369
370class _BoundedSemaphore(_Semaphore):
371 """Semaphore that checks that # releases is <= # acquires"""
372 def __init__(self, value=1, verbose=None):
373 _Semaphore.__init__(self, value, verbose)
374 self._initial_value = value
375
376 def release(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000377 if self._value >= self._initial_value:
Collin Winterce36ad82007-08-30 01:19:48 +0000378 raise ValueError("Semaphore released too many times")
Skip Montanaroe428bb72001-08-20 20:27:58 +0000379 return _Semaphore.release(self)
380
381
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000382def Event(*args, **kwargs):
Guido van Rossum68468eb2003-02-27 20:14:51 +0000383 return _Event(*args, **kwargs)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000384
385class _Event(_Verbose):
386
387 # After Tim Peters' event class (without is_posted())
388
389 def __init__(self, verbose=None):
390 _Verbose.__init__(self, verbose)
Guido van Rossumd0648992007-08-20 19:25:41 +0000391 self._cond = Condition(Lock())
392 self._flag = False
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000393
Gregory P. Smith9bd4a242011-01-04 18:33:38 +0000394 def _reset_internal_locks(self):
395 # private! called by Thread._reset_internal_locks by _after_fork()
396 self._cond.__init__()
397
Benjamin Peterson672b8032008-06-11 19:14:14 +0000398 def is_set(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000399 return self._flag
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000400
Benjamin Petersonb3085c92008-09-01 23:09:31 +0000401 isSet = is_set
Benjamin Petersonf0923f52008-08-18 22:10:13 +0000402
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000403 def set(self):
Christian Heimes969fe572008-01-25 11:23:10 +0000404 self._cond.acquire()
405 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000406 self._flag = True
Benjamin Peterson672b8032008-06-11 19:14:14 +0000407 self._cond.notify_all()
Christian Heimes969fe572008-01-25 11:23:10 +0000408 finally:
409 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000410
411 def clear(self):
Christian Heimes969fe572008-01-25 11:23:10 +0000412 self._cond.acquire()
413 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000414 self._flag = False
Christian Heimes969fe572008-01-25 11:23:10 +0000415 finally:
416 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000417
418 def wait(self, timeout=None):
Christian Heimes969fe572008-01-25 11:23:10 +0000419 self._cond.acquire()
420 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000421 if not self._flag:
422 self._cond.wait(timeout)
Benjamin Petersond23f8222009-04-05 19:13:16 +0000423 return self._flag
Christian Heimes969fe572008-01-25 11:23:10 +0000424 finally:
425 self._cond.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000426
Kristján Valur Jónsson3be00032010-10-28 09:43:10 +0000427
428# A barrier class. Inspired in part by the pthread_barrier_* api and
429# the CyclicBarrier class from Java. See
430# http://sourceware.org/pthreads-win32/manual/pthread_barrier_init.html and
431# http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/
432# CyclicBarrier.html
433# for information.
434# We maintain two main states, 'filling' and 'draining' enabling the barrier
435# to be cyclic. Threads are not allowed into it until it has fully drained
436# since the previous cycle. In addition, a 'resetting' state exists which is
437# similar to 'draining' except that threads leave with a BrokenBarrierError,
438# and a 'broken' state in which all threads get get the exception.
439class Barrier(_Verbose):
440 """
441 Barrier. Useful for synchronizing a fixed number of threads
442 at known synchronization points. Threads block on 'wait()' and are
443 simultaneously once they have all made that call.
444 """
445 def __init__(self, parties, action=None, timeout=None, verbose=None):
446 """
447 Create a barrier, initialised to 'parties' threads.
448 'action' is a callable which, when supplied, will be called
449 by one of the threads after they have all entered the
450 barrier and just prior to releasing them all.
451 If a 'timeout' is provided, it is uses as the default for
452 all subsequent 'wait()' calls.
453 """
454 _Verbose.__init__(self, verbose)
455 self._cond = Condition(Lock())
456 self._action = action
457 self._timeout = timeout
458 self._parties = parties
459 self._state = 0 #0 filling, 1, draining, -1 resetting, -2 broken
460 self._count = 0
461
462 def wait(self, timeout=None):
463 """
464 Wait for the barrier. When the specified number of threads have
465 started waiting, they are all simultaneously awoken. If an 'action'
466 was provided for the barrier, one of the threads will have executed
467 that callback prior to returning.
468 Returns an individual index number from 0 to 'parties-1'.
469 """
470 if timeout is None:
471 timeout = self._timeout
472 with self._cond:
473 self._enter() # Block while the barrier drains.
474 index = self._count
475 self._count += 1
476 try:
477 if index + 1 == self._parties:
478 # We release the barrier
479 self._release()
480 else:
481 # We wait until someone releases us
482 self._wait(timeout)
483 return index
484 finally:
485 self._count -= 1
486 # Wake up any threads waiting for barrier to drain.
487 self._exit()
488
489 # Block until the barrier is ready for us, or raise an exception
490 # if it is broken.
491 def _enter(self):
492 while self._state in (-1, 1):
493 # It is draining or resetting, wait until done
494 self._cond.wait()
495 #see if the barrier is in a broken state
496 if self._state < 0:
497 raise BrokenBarrierError
498 assert self._state == 0
499
500 # Optionally run the 'action' and release the threads waiting
501 # in the barrier.
502 def _release(self):
503 try:
504 if self._action:
505 self._action()
506 # enter draining state
507 self._state = 1
508 self._cond.notify_all()
509 except:
510 #an exception during the _action handler. Break and reraise
511 self._break()
512 raise
513
514 # Wait in the barrier until we are relased. Raise an exception
515 # if the barrier is reset or broken.
516 def _wait(self, timeout):
Kristján Valur Jónsson63315202010-11-18 12:46:39 +0000517 if not self._cond.wait_for(lambda : self._state != 0, timeout):
518 #timed out. Break the barrier
519 self._break()
520 raise BrokenBarrierError
521 if self._state < 0:
522 raise BrokenBarrierError
Kristján Valur Jónsson3be00032010-10-28 09:43:10 +0000523 assert self._state == 1
524
525 # If we are the last thread to exit the barrier, signal any threads
526 # waiting for the barrier to drain.
527 def _exit(self):
528 if self._count == 0:
529 if self._state in (-1, 1):
530 #resetting or draining
531 self._state = 0
532 self._cond.notify_all()
533
534 def reset(self):
535 """
536 Reset the barrier to the initial state.
537 Any threads currently waiting will get the BrokenBarrier exception
538 raised.
539 """
540 with self._cond:
541 if self._count > 0:
542 if self._state == 0:
543 #reset the barrier, waking up threads
544 self._state = -1
545 elif self._state == -2:
546 #was broken, set it to reset state
547 #which clears when the last thread exits
548 self._state = -1
549 else:
550 self._state = 0
551 self._cond.notify_all()
552
553 def abort(self):
554 """
555 Place the barrier into a 'broken' state.
556 Useful in case of error. Any currently waiting threads and
557 threads attempting to 'wait()' will have BrokenBarrierError
558 raised.
559 """
560 with self._cond:
561 self._break()
562
563 def _break(self):
564 # An internal error was detected. The barrier is set to
565 # a broken state all parties awakened.
566 self._state = -2
567 self._cond.notify_all()
568
569 @property
570 def parties(self):
571 """
572 Return the number of threads required to trip the barrier.
573 """
574 return self._parties
575
576 @property
577 def n_waiting(self):
578 """
579 Return the number of threads that are currently waiting at the barrier.
580 """
581 # We don't need synchronization here since this is an ephemeral result
582 # anyway. It returns the correct value in the steady state.
583 if self._state == 0:
584 return self._count
585 return 0
586
587 @property
588 def broken(self):
589 """
590 Return True if the barrier is in a broken state
591 """
592 return self._state == -2
593
594#exception raised by the Barrier class
595class BrokenBarrierError(RuntimeError): pass
596
597
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000598# Helper to generate new thread names
599_counter = 0
600def _newname(template="Thread-%d"):
601 global _counter
602 _counter = _counter + 1
603 return template % _counter
604
605# Active thread administration
606_active_limbo_lock = _allocate_lock()
Tim Peters711906e2005-01-08 07:30:42 +0000607_active = {} # maps thread id to Thread object
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000608_limbo = {}
609
Antoine Pitrouc081c0c2011-07-15 22:12:24 +0200610# For debug and leak testing
611_dangling = WeakSet()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000612
613# Main class for threads
614
615class Thread(_Verbose):
616
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000617 __initialized = False
Brett Cannoncc4e9352004-07-03 03:52:35 +0000618 # Need to store a reference to sys.exc_info for printing
619 # out exceptions when a thread tries to use a global var. during interp.
620 # shutdown and thus raises an exception about trying to perform some
621 # operation on/with a NoneType
622 __exc_info = _sys.exc_info
Christian Heimesbbe741d2008-03-28 10:53:29 +0000623 # Keep sys.exc_clear too to clear the exception just before
624 # allowing .join() to return.
625 #XXX __exc_clear = _sys.exc_clear
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000626
627 def __init__(self, group=None, target=None, name=None,
Georg Brandla4a8b822005-07-15 09:13:21 +0000628 args=(), kwargs=None, verbose=None):
Guido van Rossum5a43e1a1998-06-09 19:04:26 +0000629 assert group is None, "group argument must be None for now"
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000630 _Verbose.__init__(self, verbose)
Georg Brandla4a8b822005-07-15 09:13:21 +0000631 if kwargs is None:
632 kwargs = {}
Guido van Rossumd0648992007-08-20 19:25:41 +0000633 self._target = target
634 self._name = str(name or _newname())
635 self._args = args
636 self._kwargs = kwargs
637 self._daemonic = self._set_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
Antoine Pitrouc081c0c2011-07-15 22:12:24 +0200646 _dangling.add(self)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000647
Gregory P. Smith9bd4a242011-01-04 18:33:38 +0000648 def _reset_internal_locks(self):
649 # private! Called by _after_fork() to reset our internal locks as
650 # they may be in an invalid state leading to a deadlock or crash.
651 if hasattr(self, '_block'): # DummyThread deletes _block
652 self._block.__init__()
653 self._started._reset_internal_locks()
654
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000655 def _set_daemon(self):
656 # Overridden in _MainThread and _DummyThread
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000657 return current_thread().daemon
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000658
659 def __repr__(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000660 assert self._initialized, "Thread.__init__() was not called"
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000661 status = "initial"
Benjamin Peterson672b8032008-06-11 19:14:14 +0000662 if self._started.is_set():
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000663 status = "started"
Guido van Rossumd0648992007-08-20 19:25:41 +0000664 if self._stopped:
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000665 status = "stopped"
Guido van Rossumd0648992007-08-20 19:25:41 +0000666 if self._daemonic:
Georg Brandl0c77a822008-06-10 16:37:50 +0000667 status += " daemon"
668 if self._ident is not None:
669 status += " %s" % self._ident
Guido van Rossumd0648992007-08-20 19:25:41 +0000670 return "<%s(%s, %s)>" % (self.__class__.__name__, self._name, status)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000671
672 def start(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000673 if not self._initialized:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000674 raise RuntimeError("thread.__init__() not called")
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000675
Benjamin Peterson672b8032008-06-11 19:14:14 +0000676 if self._started.is_set():
Senthil Kumaranfdd4d0f2010-04-06 03:30:18 +0000677 raise RuntimeError("threads can only be started once")
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000678 if __debug__:
679 self._note("%s.start(): starting thread", self)
Benjamin Petersond23f8222009-04-05 19:13:16 +0000680 with _active_limbo_lock:
681 _limbo[self] = self
Gregory P. Smith3fdd9642010-02-28 18:57:46 +0000682 try:
683 _start_new_thread(self._bootstrap, ())
684 except Exception:
685 with _active_limbo_lock:
686 del _limbo[self]
687 raise
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000688 self._started.wait()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000689
690 def run(self):
Christian Heimesd3eb5a152008-02-24 00:38:49 +0000691 try:
692 if self._target:
693 self._target(*self._args, **self._kwargs)
694 finally:
695 # Avoid a refcycle if the thread is running a function with
696 # an argument that has a member that points to the thread.
697 del self._target, self._args, self._kwargs
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000698
Guido van Rossumd0648992007-08-20 19:25:41 +0000699 def _bootstrap(self):
Guido van Rossum61e21b52007-08-20 19:06:03 +0000700 # Wrapper around the real bootstrap code that ignores
701 # exceptions during interpreter cleanup. Those typically
702 # happen when a daemon thread wakes up at an unfortunate
703 # moment, finds the world around it destroyed, and raises some
704 # random exception *** while trying to report the exception in
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000705 # _bootstrap_inner() below ***. Those random exceptions
Guido van Rossum61e21b52007-08-20 19:06:03 +0000706 # don't help anybody, and they confuse users, so we suppress
707 # them. We suppress them only when it appears that the world
708 # indeed has already been destroyed, so that exceptions in
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000709 # _bootstrap_inner() during normal business hours are properly
Guido van Rossum61e21b52007-08-20 19:06:03 +0000710 # reported. Also, we only suppress them for daemonic threads;
711 # if a non-daemonic encounters this, something else is wrong.
712 try:
Guido van Rossumd0648992007-08-20 19:25:41 +0000713 self._bootstrap_inner()
Guido van Rossum61e21b52007-08-20 19:06:03 +0000714 except:
Guido van Rossumd0648992007-08-20 19:25:41 +0000715 if self._daemonic and _sys is None:
Guido van Rossum61e21b52007-08-20 19:06:03 +0000716 return
717 raise
718
Benjamin Petersond23f8222009-04-05 19:13:16 +0000719 def _set_ident(self):
720 self._ident = _get_ident()
721
Guido van Rossumd0648992007-08-20 19:25:41 +0000722 def _bootstrap_inner(self):
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000723 try:
Benjamin Petersond23f8222009-04-05 19:13:16 +0000724 self._set_ident()
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000725 self._started.set()
Benjamin Petersond23f8222009-04-05 19:13:16 +0000726 with _active_limbo_lock:
727 _active[self._ident] = self
728 del _limbo[self]
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000729 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000730 self._note("%s._bootstrap(): thread started", self)
Jeremy Hyltonbfccb352003-06-29 16:58:41 +0000731
732 if _trace_hook:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000733 self._note("%s._bootstrap(): registering trace hook", self)
Jeremy Hyltonbfccb352003-06-29 16:58:41 +0000734 _sys.settrace(_trace_hook)
735 if _profile_hook:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000736 self._note("%s._bootstrap(): registering profile hook", self)
Jeremy Hyltonbfccb352003-06-29 16:58:41 +0000737 _sys.setprofile(_profile_hook)
Tim Petersd1b108b2003-06-29 17:24:17 +0000738
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000739 try:
740 self.run()
741 except SystemExit:
742 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000743 self._note("%s._bootstrap(): raised SystemExit", self)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000744 except:
745 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000746 self._note("%s._bootstrap(): unhandled exception", self)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000747 # If sys.stderr is no more (most likely from interpreter
Guido van Rossumd0648992007-08-20 19:25:41 +0000748 # shutdown) use self._stderr. Otherwise still use sys (as in
Brett Cannoncc4e9352004-07-03 03:52:35 +0000749 # _sys) in case sys.stderr was redefined since the creation of
750 # self.
751 if _sys:
752 _sys.stderr.write("Exception in thread %s:\n%s\n" %
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000753 (self.name, _format_exc()))
Brett Cannoncc4e9352004-07-03 03:52:35 +0000754 else:
755 # Do the best job possible w/o a huge amt. of code to
756 # approximate a traceback (code ideas from
757 # Lib/traceback.py)
Guido van Rossumd0648992007-08-20 19:25:41 +0000758 exc_type, exc_value, exc_tb = self._exc_info()
Brett Cannoncc4e9352004-07-03 03:52:35 +0000759 try:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000760 print((
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000761 "Exception in thread " + self.name +
Guido van Rossumd0648992007-08-20 19:25:41 +0000762 " (most likely raised during interpreter shutdown):"), file=self._stderr)
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000763 print((
Guido van Rossumd0648992007-08-20 19:25:41 +0000764 "Traceback (most recent call last):"), file=self._stderr)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000765 while exc_tb:
Guido van Rossumbe19ed72007-02-09 05:37:30 +0000766 print((
Brett Cannoncc4e9352004-07-03 03:52:35 +0000767 ' File "%s", line %s, in %s' %
768 (exc_tb.tb_frame.f_code.co_filename,
769 exc_tb.tb_lineno,
Guido van Rossumd0648992007-08-20 19:25:41 +0000770 exc_tb.tb_frame.f_code.co_name)), file=self._stderr)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000771 exc_tb = exc_tb.tb_next
Guido van Rossumd0648992007-08-20 19:25:41 +0000772 print(("%s: %s" % (exc_type, exc_value)), file=self._stderr)
Brett Cannoncc4e9352004-07-03 03:52:35 +0000773 # Make sure that exc_tb gets deleted since it is a memory
774 # hog; deleting everything else is just for thoroughness
775 finally:
776 del exc_type, exc_value, exc_tb
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000777 else:
778 if __debug__:
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000779 self._note("%s._bootstrap(): normal return", self)
Christian Heimesbbe741d2008-03-28 10:53:29 +0000780 finally:
781 # Prevent a race in
782 # test_threading.test_no_refcycle_through_target when
783 # the exception keeps the target alive past when we
784 # assert that it's dead.
785 #XXX self.__exc_clear()
786 pass
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000787 finally:
Christian Heimes1af737c2008-01-23 08:24:23 +0000788 with _active_limbo_lock:
789 self._stop()
790 try:
Georg Brandl0c77a822008-06-10 16:37:50 +0000791 # We don't call self._delete() because it also
Christian Heimes1af737c2008-01-23 08:24:23 +0000792 # grabs _active_limbo_lock.
793 del _active[_get_ident()]
794 except:
795 pass
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000796
Guido van Rossumd0648992007-08-20 19:25:41 +0000797 def _stop(self):
Christian Heimes969fe572008-01-25 11:23:10 +0000798 self._block.acquire()
799 self._stopped = True
Benjamin Peterson672b8032008-06-11 19:14:14 +0000800 self._block.notify_all()
Christian Heimes969fe572008-01-25 11:23:10 +0000801 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000802
Guido van Rossumd0648992007-08-20 19:25:41 +0000803 def _delete(self):
Tim Peters21429932004-07-21 03:36:52 +0000804 "Remove current thread from the dict of currently running threads."
Brett Cannon8b3d92a2004-07-21 02:21:58 +0000805
Georg Brandl2067bfd2008-05-25 13:05:15 +0000806 # Notes about running with _dummy_thread:
Tim Peters21429932004-07-21 03:36:52 +0000807 #
Georg Brandl2067bfd2008-05-25 13:05:15 +0000808 # Must take care to not raise an exception if _dummy_thread is being
Tim Peters21429932004-07-21 03:36:52 +0000809 # used (and thus this module is being used as an instance of
Georg Brandl2067bfd2008-05-25 13:05:15 +0000810 # dummy_threading). _dummy_thread.get_ident() always returns -1 since
811 # there is only one thread if _dummy_thread is being used. Thus
Tim Peters21429932004-07-21 03:36:52 +0000812 # len(_active) is always <= 1 here, and any Thread instance created
813 # overwrites the (if any) thread currently registered in _active.
814 #
815 # An instance of _MainThread is always created by 'threading'. This
816 # gets overwritten the instant an instance of Thread is created; both
Georg Brandl2067bfd2008-05-25 13:05:15 +0000817 # threads return -1 from _dummy_thread.get_ident() and thus have the
Tim Peters21429932004-07-21 03:36:52 +0000818 # same key in the dict. So when the _MainThread instance created by
819 # 'threading' tries to clean itself up when atexit calls this method
820 # it gets a KeyError if another Thread instance was created.
821 #
822 # This all means that KeyError from trying to delete something from
823 # _active if dummy_threading is being used is a red herring. But
824 # since it isn't if dummy_threading is *not* being used then don't
825 # hide the exception.
Brett Cannon8b3d92a2004-07-21 02:21:58 +0000826
Christian Heimes969fe572008-01-25 11:23:10 +0000827 try:
Neal Norwitzf5c7c2e2008-04-05 04:47:45 +0000828 with _active_limbo_lock:
Brett Cannon8b3d92a2004-07-21 02:21:58 +0000829 del _active[_get_ident()]
Neal Norwitzf5c7c2e2008-04-05 04:47:45 +0000830 # There must not be any python code between the previous line
831 # and after the lock is released. Otherwise a tracing function
832 # could try to acquire the lock again in the same thread, (in
Benjamin Peterson672b8032008-06-11 19:14:14 +0000833 # current_thread()), and would block.
Neal Norwitzf5c7c2e2008-04-05 04:47:45 +0000834 except KeyError:
835 if 'dummy_threading' not in _sys.modules:
836 raise
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000837
838 def join(self, timeout=None):
Guido van Rossumd0648992007-08-20 19:25:41 +0000839 if not self._initialized:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000840 raise RuntimeError("Thread.__init__() not called")
Benjamin Peterson672b8032008-06-11 19:14:14 +0000841 if not self._started.is_set():
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000842 raise RuntimeError("cannot join thread before it is started")
Benjamin Peterson672b8032008-06-11 19:14:14 +0000843 if self is current_thread():
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000844 raise RuntimeError("cannot join current thread")
845
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000846 if __debug__:
Guido van Rossumd0648992007-08-20 19:25:41 +0000847 if not self._stopped:
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000848 self._note("%s.join(): waiting until thread stops", self)
Christian Heimes969fe572008-01-25 11:23:10 +0000849
850 self._block.acquire()
851 try:
Brett Cannonad07ff22005-11-23 02:15:50 +0000852 if timeout is None:
Guido van Rossumd0648992007-08-20 19:25:41 +0000853 while not self._stopped:
854 self._block.wait()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000855 if __debug__:
856 self._note("%s.join(): thread stopped", self)
Brett Cannonad07ff22005-11-23 02:15:50 +0000857 else:
858 deadline = _time() + timeout
Guido van Rossumd0648992007-08-20 19:25:41 +0000859 while not self._stopped:
Brett Cannonad07ff22005-11-23 02:15:50 +0000860 delay = deadline - _time()
861 if delay <= 0:
862 if __debug__:
863 self._note("%s.join(): timed out", self)
864 break
Guido van Rossumd0648992007-08-20 19:25:41 +0000865 self._block.wait(delay)
Brett Cannonad07ff22005-11-23 02:15:50 +0000866 else:
867 if __debug__:
868 self._note("%s.join(): thread stopped", self)
Christian Heimes969fe572008-01-25 11:23:10 +0000869 finally:
870 self._block.release()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000871
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000872 @property
873 def name(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000874 assert self._initialized, "Thread.__init__() not called"
875 return self._name
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000876
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000877 @name.setter
878 def name(self, name):
Guido van Rossumd0648992007-08-20 19:25:41 +0000879 assert self._initialized, "Thread.__init__() not called"
880 self._name = str(name)
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000881
Benjamin Peterson773c17b2008-08-18 16:45:31 +0000882 @property
883 def ident(self):
Georg Brandl0c77a822008-06-10 16:37:50 +0000884 assert self._initialized, "Thread.__init__() not called"
885 return self._ident
886
Benjamin Peterson672b8032008-06-11 19:14:14 +0000887 def is_alive(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000888 assert self._initialized, "Thread.__init__() not called"
Benjamin Peterson672b8032008-06-11 19:14:14 +0000889 return self._started.is_set() and not self._stopped
Tim Petersb90f89a2001-01-15 03:26:36 +0000890
Benjamin Petersonb3085c92008-09-01 23:09:31 +0000891 isAlive = is_alive
Benjamin Petersonf0923f52008-08-18 22:10:13 +0000892
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000893 @property
894 def daemon(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000895 assert self._initialized, "Thread.__init__() not called"
896 return self._daemonic
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000897
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000898 @daemon.setter
899 def daemon(self, daemonic):
Guido van Rossumd0648992007-08-20 19:25:41 +0000900 if not self._initialized:
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000901 raise RuntimeError("Thread.__init__() not called")
Benjamin Peterson672b8032008-06-11 19:14:14 +0000902 if self._started.is_set():
Guido van Rossumcd16bf62007-06-13 18:07:49 +0000903 raise RuntimeError("cannot set daemon status of active thread");
Guido van Rossumd0648992007-08-20 19:25:41 +0000904 self._daemonic = daemonic
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000905
Benjamin Peterson6640d722008-08-18 18:16:46 +0000906 def isDaemon(self):
907 return self.daemon
908
909 def setDaemon(self, daemonic):
910 self.daemon = daemonic
911
912 def getName(self):
913 return self.name
914
915 def setName(self, name):
916 self.name = name
917
Martin v. Löwis44f86962001-09-05 13:44:54 +0000918# The timer class was contributed by Itamar Shtull-Trauring
919
920def Timer(*args, **kwargs):
921 return _Timer(*args, **kwargs)
922
923class _Timer(Thread):
924 """Call a function after a specified number of seconds:
Tim Petersb64bec32001-09-18 02:26:39 +0000925
Martin v. Löwis44f86962001-09-05 13:44:54 +0000926 t = Timer(30.0, f, args=[], kwargs={})
927 t.start()
928 t.cancel() # stop the timer's action if it's still waiting
929 """
Tim Petersb64bec32001-09-18 02:26:39 +0000930
Martin v. Löwis44f86962001-09-05 13:44:54 +0000931 def __init__(self, interval, function, args=[], kwargs={}):
932 Thread.__init__(self)
933 self.interval = interval
934 self.function = function
935 self.args = args
936 self.kwargs = kwargs
937 self.finished = Event()
Tim Petersb64bec32001-09-18 02:26:39 +0000938
Martin v. Löwis44f86962001-09-05 13:44:54 +0000939 def cancel(self):
940 """Stop the timer if it hasn't finished yet"""
941 self.finished.set()
Tim Petersb64bec32001-09-18 02:26:39 +0000942
Martin v. Löwis44f86962001-09-05 13:44:54 +0000943 def run(self):
944 self.finished.wait(self.interval)
Benjamin Peterson672b8032008-06-11 19:14:14 +0000945 if not self.finished.is_set():
Martin v. Löwis44f86962001-09-05 13:44:54 +0000946 self.function(*self.args, **self.kwargs)
947 self.finished.set()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000948
949# Special thread class to represent the main thread
950# This is garbage collected through an exit handler
951
952class _MainThread(Thread):
953
954 def __init__(self):
955 Thread.__init__(self, name="MainThread")
Christian Heimes9e7f1d22008-02-28 12:27:11 +0000956 self._started.set()
Benjamin Petersond23f8222009-04-05 19:13:16 +0000957 self._set_ident()
958 with _active_limbo_lock:
959 _active[self._ident] = self
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000960
961 def _set_daemon(self):
Guido van Rossum8ca162f2002-04-07 06:36:23 +0000962 return False
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000963
Thomas Wouters902d6eb2007-01-09 23:18:33 +0000964 def _exitfunc(self):
Guido van Rossumd0648992007-08-20 19:25:41 +0000965 self._stop()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000966 t = _pickSomeNonDaemonThread()
967 if t:
968 if __debug__:
969 self._note("%s: waiting for other threads", self)
970 while t:
971 t.join()
972 t = _pickSomeNonDaemonThread()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000973 if __debug__:
974 self._note("%s: exiting", self)
Guido van Rossumd0648992007-08-20 19:25:41 +0000975 self._delete()
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000976
977def _pickSomeNonDaemonThread():
978 for t in enumerate():
Benjamin Petersonfdbea962008-08-18 17:33:47 +0000979 if not t.daemon and t.is_alive():
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000980 return t
981 return None
982
983
984# Dummy thread class to represent threads not started here.
Tim Peters711906e2005-01-08 07:30:42 +0000985# These aren't garbage collected when they die, nor can they be waited for.
Benjamin Peterson672b8032008-06-11 19:14:14 +0000986# If they invoke anything in threading.py that calls current_thread(), they
Tim Peters711906e2005-01-08 07:30:42 +0000987# leave an entry in the _active dict forever after.
Benjamin Peterson672b8032008-06-11 19:14:14 +0000988# Their purpose is to return *something* from current_thread().
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000989# They are marked as daemon threads so we won't wait for them
990# when we exit (conform previous semantics).
991
992class _DummyThread(Thread):
Tim Petersb90f89a2001-01-15 03:26:36 +0000993
Guido van Rossum7f5013a1998-04-09 22:01:42 +0000994 def __init__(self):
995 Thread.__init__(self, name=_newname("Dummy-%d"))
Tim Peters711906e2005-01-08 07:30:42 +0000996
Gregory P. Smith9bd4a242011-01-04 18:33:38 +0000997 # Thread._block consumes an OS-level locking primitive, which
Tim Peters711906e2005-01-08 07:30:42 +0000998 # can never be used by a _DummyThread. Since a _DummyThread
999 # instance is immortal, that's bad, so release this resource.
Guido van Rossumd0648992007-08-20 19:25:41 +00001000 del self._block
Tim Peters711906e2005-01-08 07:30:42 +00001001
Christian Heimes9e7f1d22008-02-28 12:27:11 +00001002 self._started.set()
Benjamin Petersond23f8222009-04-05 19:13:16 +00001003 self._set_ident()
1004 with _active_limbo_lock:
1005 _active[self._ident] = self
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001006
1007 def _set_daemon(self):
Guido van Rossum8ca162f2002-04-07 06:36:23 +00001008 return True
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001009
Neal Norwitz45bec8c2002-02-19 03:01:36 +00001010 def join(self, timeout=None):
Guido van Rossum8ca162f2002-04-07 06:36:23 +00001011 assert False, "cannot join a dummy thread"
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001012
1013
1014# Global API functions
1015
Benjamin Peterson672b8032008-06-11 19:14:14 +00001016def current_thread():
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001017 try:
1018 return _active[_get_ident()]
1019 except KeyError:
Benjamin Peterson672b8032008-06-11 19:14:14 +00001020 ##print "current_thread(): no current thread for", _get_ident()
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001021 return _DummyThread()
1022
Benjamin Petersonb3085c92008-09-01 23:09:31 +00001023currentThread = current_thread
Benjamin Petersonf0923f52008-08-18 22:10:13 +00001024
Benjamin Peterson672b8032008-06-11 19:14:14 +00001025def active_count():
Benjamin Petersond23f8222009-04-05 19:13:16 +00001026 with _active_limbo_lock:
1027 return len(_active) + len(_limbo)
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001028
Benjamin Petersonb3085c92008-09-01 23:09:31 +00001029activeCount = active_count
Benjamin Petersonf0923f52008-08-18 22:10:13 +00001030
Antoine Pitroubdec11f2009-11-05 13:49:14 +00001031def _enumerate():
1032 # Same as enumerate(), but without the lock. Internal use only.
1033 return list(_active.values()) + list(_limbo.values())
1034
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001035def enumerate():
Benjamin Petersond23f8222009-04-05 19:13:16 +00001036 with _active_limbo_lock:
1037 return list(_active.values()) + list(_limbo.values())
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001038
Georg Brandl2067bfd2008-05-25 13:05:15 +00001039from _thread import stack_size
Thomas Wouters0e3f5912006-08-11 14:57:12 +00001040
Thomas Wouters902d6eb2007-01-09 23:18:33 +00001041# Create the main thread object,
1042# and make it available for the interpreter
1043# (Py_Main) as threading._shutdown.
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001044
Thomas Wouters902d6eb2007-01-09 23:18:33 +00001045_shutdown = _MainThread()._exitfunc
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001046
Jim Fultond15dc062004-07-14 19:11:50 +00001047# get thread-local implementation, either from the thread
1048# module, or from the python fallback
1049
1050try:
Georg Brandl2067bfd2008-05-25 13:05:15 +00001051 from _thread import _local as local
Jim Fultond15dc062004-07-14 19:11:50 +00001052except ImportError:
1053 from _threading_local import local
1054
Guido van Rossum7f5013a1998-04-09 22:01:42 +00001055
Jesse Nollera8513972008-07-17 16:49:17 +00001056def _after_fork():
1057 # This function is called by Python/ceval.c:PyEval_ReInitThreads which
1058 # is called from PyOS_AfterFork. Here we cleanup threading module state
1059 # that should not exist after a fork.
1060
1061 # Reset _active_limbo_lock, in case we forked while the lock was held
1062 # by another (non-forked) thread. http://bugs.python.org/issue874900
1063 global _active_limbo_lock
1064 _active_limbo_lock = _allocate_lock()
1065
1066 # fork() only copied the current thread; clear references to others.
1067 new_active = {}
1068 current = current_thread()
1069 with _active_limbo_lock:
Antoine Pitrou5fe291f2008-09-06 23:00:03 +00001070 for thread in _active.values():
Jesse Nollera8513972008-07-17 16:49:17 +00001071 if thread is current:
Antoine Pitrou5fe291f2008-09-06 23:00:03 +00001072 # There is only one active thread. We reset the ident to
1073 # its new value since it can have changed.
1074 ident = _get_ident()
1075 thread._ident = ident
Gregory P. Smith96c886c2011-01-03 21:06:12 +00001076 # Any condition variables hanging off of the active thread may
1077 # be in an invalid state, so we reinitialize them.
Gregory P. Smith9bd4a242011-01-04 18:33:38 +00001078 thread._reset_internal_locks()
Jesse Nollera8513972008-07-17 16:49:17 +00001079 new_active[ident] = thread
1080 else:
1081 # All the others are already stopped.
1082 # We don't call _Thread__stop() because it tries to acquire
1083 # thread._Thread__block which could also have been held while
1084 # we forked.
Antoine Pitrou5fe291f2008-09-06 23:00:03 +00001085 thread._stopped = True
Jesse Nollera8513972008-07-17 16:49:17 +00001086
1087 _limbo.clear()
1088 _active.clear()
1089 _active.update(new_active)
1090 assert len(_active) == 1