Python code coverage for Lib/threading.py

#	count	content
1	n/a	"""Thread module emulating a subset of Java's threading model."""
2	n/a
3	n/a	import sys as _sys
4	n/a	import _thread
5	n/a
6	n/a	from time import monotonic as _time
7	n/a	from traceback import format_exc as _format_exc
8	n/a	from _weakrefset import WeakSet
9	n/a	from itertools import islice as _islice, count as _count
10	n/a	try:
11	n/a	from _collections import deque as _deque
12	n/a	except ImportError:
13	n/a	from collections import deque as _deque
14	n/a
15	n/a	# Note regarding PEP 8 compliant names
16	n/a	# This threading model was originally inspired by Java, and inherited
17	n/a	# the convention of camelCase function and method names from that
18	n/a	# language. Those original names are not in any imminent danger of
19	n/a	# being deprecated (even for Py3k),so this module provides them as an
20	n/a	# alias for the PEP 8 compliant names
21	n/a	# Note that using the new PEP 8 compliant names facilitates substitution
22	n/a	# with the multiprocessing module, which doesn't provide the old
23	n/a	# Java inspired names.
24	n/a
25	n/a	__all__ = ['get_ident', 'active_count', 'Condition', 'current_thread',
26	n/a	'enumerate', 'main_thread', 'TIMEOUT_MAX',
27	n/a	'Event', 'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Thread',
28	n/a	'Barrier', 'BrokenBarrierError', 'Timer', 'ThreadError',
29	n/a	'setprofile', 'settrace', 'local', 'stack_size']
30	n/a
31	n/a	# Rename some stuff so "from threading import *" is safe
32	n/a	_start_new_thread = _thread.start_new_thread
33	n/a	_allocate_lock = _thread.allocate_lock
34	n/a	_set_sentinel = _thread._set_sentinel
35	n/a	get_ident = _thread.get_ident
36	n/a	ThreadError = _thread.error
37	n/a	try:
38	n/a	_CRLock = _thread.RLock
39	n/a	except AttributeError:
40	n/a	_CRLock = None
41	n/a	TIMEOUT_MAX = _thread.TIMEOUT_MAX
42	n/a	del _thread
43	n/a
44	n/a
45	n/a	# Support for profile and trace hooks
46	n/a
47	n/a	_profile_hook = None
48	n/a	_trace_hook = None
49	n/a
50	n/a	def setprofile(func):
51	n/a	"""Set a profile function for all threads started from the threading module.
52	n/a
53	n/a	The func will be passed to sys.setprofile() for each thread, before its
54	n/a	run() method is called.
55	n/a
56	n/a	"""
57	n/a	global _profile_hook
58	n/a	_profile_hook = func
59	n/a
60	n/a	def settrace(func):
61	n/a	"""Set a trace function for all threads started from the threading module.
62	n/a
63	n/a	The func will be passed to sys.settrace() for each thread, before its run()
64	n/a	method is called.
65	n/a
66	n/a	"""
67	n/a	global _trace_hook
68	n/a	_trace_hook = func
69	n/a
70	n/a	# Synchronization classes
71	n/a
72	n/a	Lock = _allocate_lock
73	n/a
74	n/a	def RLock(args, *kwargs):
75	n/a	"""Factory function that returns a new reentrant lock.
76	n/a
77	n/a	A reentrant lock must be released by the thread that acquired it. Once a
78	n/a	thread has acquired a reentrant lock, the same thread may acquire it again
79	n/a	without blocking; the thread must release it once for each time it has
80	n/a	acquired it.
81	n/a
82	n/a	"""
83	n/a	if _CRLock is None:
84	n/a	return _PyRLock(args, *kwargs)
85	n/a	return _CRLock(args, *kwargs)
86	n/a
87	n/a	class _RLock:
88	n/a	"""This class implements reentrant lock objects.
89	n/a
90	n/a	A reentrant lock must be released by the thread that acquired it. Once a
91	n/a	thread has acquired a reentrant lock, the same thread may acquire it
92	n/a	again without blocking; the thread must release it once for each time it
93	n/a	has acquired it.
94	n/a
95	n/a	"""
96	n/a
97	n/a	def __init__(self):
98	n/a	self._block = _allocate_lock()
99	n/a	self._owner = None
100	n/a	self._count = 0
101	n/a
102	n/a	def __repr__(self):
103	n/a	owner = self._owner
104	n/a	try:
105	n/a	owner = _active[owner].name
106	n/a	except KeyError:
107	n/a	pass
108	n/a	return "<%s %s.%s object owner=%r count=%d at %s>" % (
109	n/a	"locked" if self._block.locked() else "unlocked",
110	n/a	self.__class__.__module__,
111	n/a	self.__class__.__qualname__,
112	n/a	owner,
113	n/a	self._count,
114	n/a	hex(id(self))
115	n/a	)
116	n/a
117	n/a	def acquire(self, blocking=True, timeout=-1):
118	n/a	"""Acquire a lock, blocking or non-blocking.
119	n/a
120	n/a	When invoked without arguments: if this thread already owns the lock,
121	n/a	increment the recursion level by one, and return immediately. Otherwise,
122	n/a	if another thread owns the lock, block until the lock is unlocked. Once
123	n/a	the lock is unlocked (not owned by any thread), then grab ownership, set
124	n/a	the recursion level to one, and return. If more than one thread is
125	n/a	blocked waiting until the lock is unlocked, only one at a time will be
126	n/a	able to grab ownership of the lock. There is no return value in this
127	n/a	case.
128	n/a
129	n/a	When invoked with the blocking argument set to true, do the same thing
130	n/a	as when called without arguments, and return true.
131	n/a
132	n/a	When invoked with the blocking argument set to false, do not block. If a
133	n/a	call without an argument would block, return false immediately;
134	n/a	otherwise, do the same thing as when called without arguments, and
135	n/a	return true.
136	n/a
137	n/a	When invoked with the floating-point timeout argument set to a positive
138	n/a	value, block for at most the number of seconds specified by timeout
139	n/a	and as long as the lock cannot be acquired. Return true if the lock has
140	n/a	been acquired, false if the timeout has elapsed.
141	n/a
142	n/a	"""
143	n/a	me = get_ident()
144	n/a	if self._owner == me:
145	n/a	self._count += 1
146	n/a	return 1
147	n/a	rc = self._block.acquire(blocking, timeout)
148	n/a	if rc:
149	n/a	self._owner = me
150	n/a	self._count = 1
151	n/a	return rc
152	n/a
153	n/a	__enter__ = acquire
154	n/a
155	n/a	def release(self):
156	n/a	"""Release a lock, decrementing the recursion level.
157	n/a
158	n/a	If after the decrement it is zero, reset the lock to unlocked (not owned
159	n/a	by any thread), and if any other threads are blocked waiting for the
160	n/a	lock to become unlocked, allow exactly one of them to proceed. If after
161	n/a	the decrement the recursion level is still nonzero, the lock remains
162	n/a	locked and owned by the calling thread.
163	n/a
164	n/a	Only call this method when the calling thread owns the lock. A
165	n/a	RuntimeError is raised if this method is called when the lock is
166	n/a	unlocked.
167	n/a
168	n/a	There is no return value.
169	n/a
170	n/a	"""
171	n/a	if self._owner != get_ident():
172	n/a	raise RuntimeError("cannot release un-acquired lock")
173	n/a	self._count = count = self._count - 1
174	n/a	if not count:
175	n/a	self._owner = None
176	n/a	self._block.release()
177	n/a
178	n/a	def __exit__(self, t, v, tb):
179	n/a	self.release()
180	n/a
181	n/a	# Internal methods used by condition variables
182	n/a
183	n/a	def _acquire_restore(self, state):
184	n/a	self._block.acquire()
185	n/a	self._count, self._owner = state
186	n/a
187	n/a	def _release_save(self):
188	n/a	if self._count == 0:
189	n/a	raise RuntimeError("cannot release un-acquired lock")
190	n/a	count = self._count
191	n/a	self._count = 0
192	n/a	owner = self._owner
193	n/a	self._owner = None
194	n/a	self._block.release()
195	n/a	return (count, owner)
196	n/a
197	n/a	def _is_owned(self):
198	n/a	return self._owner == get_ident()
199	n/a
200	n/a	_PyRLock = _RLock
201	n/a
202	n/a
203	n/a	class Condition:
204	n/a	"""Class that implements a condition variable.
205	n/a
206	n/a	A condition variable allows one or more threads to wait until they are
207	n/a	notified by another thread.
208	n/a
209	n/a	If the lock argument is given and not None, it must be a Lock or RLock
210	n/a	object, and it is used as the underlying lock. Otherwise, a new RLock object
211	n/a	is created and used as the underlying lock.
212	n/a
213	n/a	"""
214	n/a
215	n/a	def __init__(self, lock=None):
216	n/a	if lock is None:
217	n/a	lock = RLock()
218	n/a	self._lock = lock
219	n/a	# Export the lock's acquire() and release() methods
220	n/a	self.acquire = lock.acquire
221	n/a	self.release = lock.release
222	n/a	# If the lock defines _release_save() and/or _acquire_restore(),
223	n/a	# these override the default implementations (which just call
224	n/a	# release() and acquire() on the lock). Ditto for _is_owned().
225	n/a	try:
226	n/a	self._release_save = lock._release_save
227	n/a	except AttributeError:
228	n/a	pass
229	n/a	try:
230	n/a	self._acquire_restore = lock._acquire_restore
231	n/a	except AttributeError:
232	n/a	pass
233	n/a	try:
234	n/a	self._is_owned = lock._is_owned
235	n/a	except AttributeError:
236	n/a	pass
237	n/a	self._waiters = _deque()
238	n/a
239	n/a	def __enter__(self):
240	n/a	return self._lock.__enter__()
241	n/a
242	n/a	def __exit__(self, *args):
243	n/a	return self._lock.__exit__(*args)
244	n/a
245	n/a	def __repr__(self):
246	n/a	return "<Condition(%s, %d)>" % (self._lock, len(self._waiters))
247	n/a
248	n/a	def _release_save(self):
249	n/a	self._lock.release() # No state to save
250	n/a
251	n/a	def _acquire_restore(self, x):
252	n/a	self._lock.acquire() # Ignore saved state
253	n/a
254	n/a	def _is_owned(self):
255	n/a	# Return True if lock is owned by current_thread.
256	n/a	# This method is called only if _lock doesn't have _is_owned().
257	n/a	if self._lock.acquire(0):
258	n/a	self._lock.release()
259	n/a	return False
260	n/a	else:
261	n/a	return True
262	n/a
263	n/a	def wait(self, timeout=None):
264	n/a	"""Wait until notified or until a timeout occurs.
265	n/a
266	n/a	If the calling thread has not acquired the lock when this method is
267	n/a	called, a RuntimeError is raised.
268	n/a
269	n/a	This method releases the underlying lock, and then blocks until it is
270	n/a	awakened by a notify() or notify_all() call for the same condition
271	n/a	variable in another thread, or until the optional timeout occurs. Once
272	n/a	awakened or timed out, it re-acquires the lock and returns.
273	n/a
274	n/a	When the timeout argument is present and not None, it should be a
275	n/a	floating point number specifying a timeout for the operation in seconds
276	n/a	(or fractions thereof).
277	n/a
278	n/a	When the underlying lock is an RLock, it is not released using its
279	n/a	release() method, since this may not actually unlock the lock when it
280	n/a	was acquired multiple times recursively. Instead, an internal interface
281	n/a	of the RLock class is used, which really unlocks it even when it has
282	n/a	been recursively acquired several times. Another internal interface is
283	n/a	then used to restore the recursion level when the lock is reacquired.
284	n/a
285	n/a	"""
286	n/a	if not self._is_owned():
287	n/a	raise RuntimeError("cannot wait on un-acquired lock")
288	n/a	waiter = _allocate_lock()
289	n/a	waiter.acquire()
290	n/a	self._waiters.append(waiter)
291	n/a	saved_state = self._release_save()
292	n/a	gotit = False
293	n/a	try: # restore state no matter what (e.g., KeyboardInterrupt)
294	n/a	if timeout is None:
295	n/a	waiter.acquire()
296	n/a	gotit = True
297	n/a	else:
298	n/a	if timeout > 0:
299	n/a	gotit = waiter.acquire(True, timeout)
300	n/a	else:
301	n/a	gotit = waiter.acquire(False)
302	n/a	return gotit
303	n/a	finally:
304	n/a	self._acquire_restore(saved_state)
305	n/a	if not gotit:
306	n/a	try:
307	n/a	self._waiters.remove(waiter)
308	n/a	except ValueError:
309	n/a	pass
310	n/a
311	n/a	def wait_for(self, predicate, timeout=None):
312	n/a	"""Wait until a condition evaluates to True.
313	n/a
314	n/a	predicate should be a callable which result will be interpreted as a
315	n/a	boolean value. A timeout may be provided giving the maximum time to
316	n/a	wait.
317	n/a
318	n/a	"""
319	n/a	endtime = None
320	n/a	waittime = timeout
321	n/a	result = predicate()
322	n/a	while not result:
323	n/a	if waittime is not None:
324	n/a	if endtime is None:
325	n/a	endtime = _time() + waittime
326	n/a	else:
327	n/a	waittime = endtime - _time()
328	n/a	if waittime <= 0:
329	n/a	break
330	n/a	self.wait(waittime)
331	n/a	result = predicate()
332	n/a	return result
333	n/a
334	n/a	def notify(self, n=1):
335	n/a	"""Wake up one or more threads waiting on this condition, if any.
336	n/a
337	n/a	If the calling thread has not acquired the lock when this method is
338	n/a	called, a RuntimeError is raised.
339	n/a
340	n/a	This method wakes up at most n of the threads waiting for the condition
341	n/a	variable; it is a no-op if no threads are waiting.
342	n/a
343	n/a	"""
344	n/a	if not self._is_owned():
345	n/a	raise RuntimeError("cannot notify on un-acquired lock")
346	n/a	all_waiters = self._waiters
347	n/a	waiters_to_notify = _deque(_islice(all_waiters, n))
348	n/a	if not waiters_to_notify:
349	n/a	return
350	n/a	for waiter in waiters_to_notify:
351	n/a	waiter.release()
352	n/a	try:
353	n/a	all_waiters.remove(waiter)
354	n/a	except ValueError:
355	n/a	pass
356	n/a
357	n/a	def notify_all(self):
358	n/a	"""Wake up all threads waiting on this condition.
359	n/a
360	n/a	If the calling thread has not acquired the lock when this method
361	n/a	is called, a RuntimeError is raised.
362	n/a
363	n/a	"""
364	n/a	self.notify(len(self._waiters))
365	n/a
366	n/a	notifyAll = notify_all
367	n/a
368	n/a
369	n/a	class Semaphore:
370	n/a	"""This class implements semaphore objects.
371	n/a
372	n/a	Semaphores manage a counter representing the number of release() calls minus
373	n/a	the number of acquire() calls, plus an initial value. The acquire() method
374	n/a	blocks if necessary until it can return without making the counter
375	n/a	negative. If not given, value defaults to 1.
376	n/a
377	n/a	"""
378	n/a
379	n/a	# After Tim Peters' semaphore class, but not quite the same (no maximum)
380	n/a
381	n/a	def __init__(self, value=1):
382	n/a	if value < 0:
383	n/a	raise ValueError("semaphore initial value must be >= 0")
384	n/a	self._cond = Condition(Lock())
385	n/a	self._value = value
386	n/a
387	n/a	def acquire(self, blocking=True, timeout=None):
388	n/a	"""Acquire a semaphore, decrementing the internal counter by one.
389	n/a
390	n/a	When invoked without arguments: if the internal counter is larger than
391	n/a	zero on entry, decrement it by one and return immediately. If it is zero
392	n/a	on entry, block, waiting until some other thread has called release() to
393	n/a	make it larger than zero. This is done with proper interlocking so that
394	n/a	if multiple acquire() calls are blocked, release() will wake exactly one
395	n/a	of them up. The implementation may pick one at random, so the order in
396	n/a	which blocked threads are awakened should not be relied on. There is no
397	n/a	return value in this case.
398	n/a
399	n/a	When invoked with blocking set to true, do the same thing as when called
400	n/a	without arguments, and return true.
401	n/a
402	n/a	When invoked with blocking set to false, do not block. If a call without
403	n/a	an argument would block, return false immediately; otherwise, do the
404	n/a	same thing as when called without arguments, and return true.
405	n/a
406	n/a	When invoked with a timeout other than None, it will block for at
407	n/a	most timeout seconds. If acquire does not complete successfully in
408	n/a	that interval, return false. Return true otherwise.
409	n/a
410	n/a	"""
411	n/a	if not blocking and timeout is not None:
412	n/a	raise ValueError("can't specify timeout for non-blocking acquire")
413	n/a	rc = False
414	n/a	endtime = None
415	n/a	with self._cond:
416	n/a	while self._value == 0:
417	n/a	if not blocking:
418	n/a	break
419	n/a	if timeout is not None:
420	n/a	if endtime is None:
421	n/a	endtime = _time() + timeout
422	n/a	else:
423	n/a	timeout = endtime - _time()
424	n/a	if timeout <= 0:
425	n/a	break
426	n/a	self._cond.wait(timeout)
427	n/a	else:
428	n/a	self._value -= 1
429	n/a	rc = True
430	n/a	return rc
431	n/a
432	n/a	__enter__ = acquire
433	n/a
434	n/a	def release(self):
435	n/a	"""Release a semaphore, incrementing the internal counter by one.
436	n/a
437	n/a	When the counter is zero on entry and another thread is waiting for it
438	n/a	to become larger than zero again, wake up that thread.
439	n/a
440	n/a	"""
441	n/a	with self._cond:
442	n/a	self._value += 1
443	n/a	self._cond.notify()
444	n/a
445	n/a	def __exit__(self, t, v, tb):
446	n/a	self.release()
447	n/a
448	n/a
449	n/a	class BoundedSemaphore(Semaphore):
450	n/a	"""Implements a bounded semaphore.
451	n/a
452	n/a	A bounded semaphore checks to make sure its current value doesn't exceed its
453	n/a	initial value. If it does, ValueError is raised. In most situations
454	n/a	semaphores are used to guard resources with limited capacity.
455	n/a
456	n/a	If the semaphore is released too many times it's a sign of a bug. If not
457	n/a	given, value defaults to 1.
458	n/a
459	n/a	Like regular semaphores, bounded semaphores manage a counter representing
460	n/a	the number of release() calls minus the number of acquire() calls, plus an
461	n/a	initial value. The acquire() method blocks if necessary until it can return
462	n/a	without making the counter negative. If not given, value defaults to 1.
463	n/a
464	n/a	"""
465	n/a
466	n/a	def __init__(self, value=1):
467	n/a	Semaphore.__init__(self, value)
468	n/a	self._initial_value = value
469	n/a
470	n/a	def release(self):
471	n/a	"""Release a semaphore, incrementing the internal counter by one.
472	n/a
473	n/a	When the counter is zero on entry and another thread is waiting for it
474	n/a	to become larger than zero again, wake up that thread.
475	n/a
476	n/a	If the number of releases exceeds the number of acquires,
477	n/a	raise a ValueError.
478	n/a
479	n/a	"""
480	n/a	with self._cond:
481	n/a	if self._value >= self._initial_value:
482	n/a	raise ValueError("Semaphore released too many times")
483	n/a	self._value += 1
484	n/a	self._cond.notify()
485	n/a
486	n/a
487	n/a	class Event:
488	n/a	"""Class implementing event objects.
489	n/a
490	n/a	Events manage a flag that can be set to true with the set() method and reset
491	n/a	to false with the clear() method. The wait() method blocks until the flag is
492	n/a	true. The flag is initially false.
493	n/a
494	n/a	"""
495	n/a
496	n/a	# After Tim Peters' event class (without is_posted())
497	n/a
498	n/a	def __init__(self):
499	n/a	self._cond = Condition(Lock())
500	n/a	self._flag = False
501	n/a
502	n/a	def _reset_internal_locks(self):
503	n/a	# private! called by Thread._reset_internal_locks by _after_fork()
504	n/a	self._cond.__init__(Lock())
505	n/a
506	n/a	def is_set(self):
507	n/a	"""Return true if and only if the internal flag is true."""
508	n/a	return self._flag
509	n/a
510	n/a	isSet = is_set
511	n/a
512	n/a	def set(self):
513	n/a	"""Set the internal flag to true.
514	n/a
515	n/a	All threads waiting for it to become true are awakened. Threads
516	n/a	that call wait() once the flag is true will not block at all.
517	n/a
518	n/a	"""
519	n/a	with self._cond:
520	n/a	self._flag = True
521	n/a	self._cond.notify_all()
522	n/a
523	n/a	def clear(self):
524	n/a	"""Reset the internal flag to false.
525	n/a
526	n/a	Subsequently, threads calling wait() will block until set() is called to
527	n/a	set the internal flag to true again.
528	n/a
529	n/a	"""
530	n/a	with self._cond:
531	n/a	self._flag = False
532	n/a
533	n/a	def wait(self, timeout=None):
534	n/a	"""Block until the internal flag is true.
535	n/a
536	n/a	If the internal flag is true on entry, return immediately. Otherwise,
537	n/a	block until another thread calls set() to set the flag to true, or until
538	n/a	the optional timeout occurs.
539	n/a
540	n/a	When the timeout argument is present and not None, it should be a
541	n/a	floating point number specifying a timeout for the operation in seconds
542	n/a	(or fractions thereof).
543	n/a
544	n/a	This method returns the internal flag on exit, so it will always return
545	n/a	True except if a timeout is given and the operation times out.
546	n/a
547	n/a	"""
548	n/a	with self._cond:
549	n/a	signaled = self._flag
550	n/a	if not signaled:
551	n/a	signaled = self._cond.wait(timeout)
552	n/a	return signaled
553	n/a
554	n/a
555	n/a	# A barrier class. Inspired in part by the pthread_barrier_* api and
556	n/a	# the CyclicBarrier class from Java. See
557	n/a	# http://sourceware.org/pthreads-win32/manual/pthread_barrier_init.html and
558	n/a	# http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/
559	n/a	# CyclicBarrier.html
560	n/a	# for information.
561	n/a	# We maintain two main states, 'filling' and 'draining' enabling the barrier
562	n/a	# to be cyclic. Threads are not allowed into it until it has fully drained
563	n/a	# since the previous cycle. In addition, a 'resetting' state exists which is
564	n/a	# similar to 'draining' except that threads leave with a BrokenBarrierError,
565	n/a	# and a 'broken' state in which all threads get the exception.
566	n/a	class Barrier:
567	n/a	"""Implements a Barrier.
568	n/a
569	n/a	Useful for synchronizing a fixed number of threads at known synchronization
570	n/a	points. Threads block on 'wait()' and are simultaneously once they have all
571	n/a	made that call.
572	n/a
573	n/a	"""
574	n/a
575	n/a	def __init__(self, parties, action=None, timeout=None):
576	n/a	"""Create a barrier, initialised to 'parties' threads.
577	n/a
578	n/a	'action' is a callable which, when supplied, will be called by one of
579	n/a	the threads after they have all entered the barrier and just prior to
580	n/a	releasing them all. If a 'timeout' is provided, it is uses as the
581	n/a	default for all subsequent 'wait()' calls.
582	n/a
583	n/a	"""
584	n/a	self._cond = Condition(Lock())
585	n/a	self._action = action
586	n/a	self._timeout = timeout
587	n/a	self._parties = parties
588	n/a	self._state = 0 #0 filling, 1, draining, -1 resetting, -2 broken
589	n/a	self._count = 0
590	n/a
591	n/a	def wait(self, timeout=None):
592	n/a	"""Wait for the barrier.
593	n/a
594	n/a	When the specified number of threads have started waiting, they are all
595	n/a	simultaneously awoken. If an 'action' was provided for the barrier, one
596	n/a	of the threads will have executed that callback prior to returning.
597	n/a	Returns an individual index number from 0 to 'parties-1'.
598	n/a
599	n/a	"""
600	n/a	if timeout is None:
601	n/a	timeout = self._timeout
602	n/a	with self._cond:
603	n/a	self._enter() # Block while the barrier drains.
604	n/a	index = self._count
605	n/a	self._count += 1
606	n/a	try:
607	n/a	if index + 1 == self._parties:
608	n/a	# We release the barrier
609	n/a	self._release()
610	n/a	else:
611	n/a	# We wait until someone releases us
612	n/a	self._wait(timeout)
613	n/a	return index
614	n/a	finally:
615	n/a	self._count -= 1
616	n/a	# Wake up any threads waiting for barrier to drain.
617	n/a	self._exit()
618	n/a
619	n/a	# Block until the barrier is ready for us, or raise an exception
620	n/a	# if it is broken.
621	n/a	def _enter(self):
622	n/a	while self._state in (-1, 1):
623	n/a	# It is draining or resetting, wait until done
624	n/a	self._cond.wait()
625	n/a	#see if the barrier is in a broken state
626	n/a	if self._state < 0:
627	n/a	raise BrokenBarrierError
628	n/a	assert self._state == 0
629	n/a
630	n/a	# Optionally run the 'action' and release the threads waiting
631	n/a	# in the barrier.
632	n/a	def _release(self):
633	n/a	try:
634	n/a	if self._action:
635	n/a	self._action()
636	n/a	# enter draining state
637	n/a	self._state = 1
638	n/a	self._cond.notify_all()
639	n/a	except:
640	n/a	#an exception during the _action handler. Break and reraise
641	n/a	self._break()
642	n/a	raise
643	n/a
644	n/a	# Wait in the barrier until we are released. Raise an exception
645	n/a	# if the barrier is reset or broken.
646	n/a	def _wait(self, timeout):
647	n/a	if not self._cond.wait_for(lambda : self._state != 0, timeout):
648	n/a	#timed out. Break the barrier
649	n/a	self._break()
650	n/a	raise BrokenBarrierError
651	n/a	if self._state < 0:
652	n/a	raise BrokenBarrierError
653	n/a	assert self._state == 1
654	n/a
655	n/a	# If we are the last thread to exit the barrier, signal any threads
656	n/a	# waiting for the barrier to drain.
657	n/a	def _exit(self):
658	n/a	if self._count == 0:
659	n/a	if self._state in (-1, 1):
660	n/a	#resetting or draining
661	n/a	self._state = 0
662	n/a	self._cond.notify_all()
663	n/a
664	n/a	def reset(self):
665	n/a	"""Reset the barrier to the initial state.
666	n/a
667	n/a	Any threads currently waiting will get the BrokenBarrier exception
668	n/a	raised.
669	n/a
670	n/a	"""
671	n/a	with self._cond:
672	n/a	if self._count > 0:
673	n/a	if self._state == 0:
674	n/a	#reset the barrier, waking up threads
675	n/a	self._state = -1
676	n/a	elif self._state == -2:
677	n/a	#was broken, set it to reset state
678	n/a	#which clears when the last thread exits
679	n/a	self._state = -1
680	n/a	else:
681	n/a	self._state = 0
682	n/a	self._cond.notify_all()
683	n/a
684	n/a	def abort(self):
685	n/a	"""Place the barrier into a 'broken' state.
686	n/a
687	n/a	Useful in case of error. Any currently waiting threads and threads
688	n/a	attempting to 'wait()' will have BrokenBarrierError raised.
689	n/a
690	n/a	"""
691	n/a	with self._cond:
692	n/a	self._break()
693	n/a
694	n/a	def _break(self):
695	n/a	# An internal error was detected. The barrier is set to
696	n/a	# a broken state all parties awakened.
697	n/a	self._state = -2
698	n/a	self._cond.notify_all()
699	n/a
700	n/a	@property
701	n/a	def parties(self):
702	n/a	"""Return the number of threads required to trip the barrier."""
703	n/a	return self._parties
704	n/a
705	n/a	@property
706	n/a	def n_waiting(self):
707	n/a	"""Return the number of threads currently waiting at the barrier."""
708	n/a	# We don't need synchronization here since this is an ephemeral result
709	n/a	# anyway. It returns the correct value in the steady state.
710	n/a	if self._state == 0:
711	n/a	return self._count
712	n/a	return 0
713	n/a
714	n/a	@property
715	n/a	def broken(self):
716	n/a	"""Return True if the barrier is in a broken state."""
717	n/a	return self._state == -2
718	n/a
719	n/a	# exception raised by the Barrier class
720	n/a	class BrokenBarrierError(RuntimeError):
721	n/a	pass
722	n/a
723	n/a
724	n/a	# Helper to generate new thread names
725	n/a	_counter = _count().__next__
726	n/a	_counter() # Consume 0 so first non-main thread has id 1.
727	n/a	def _newname(template="Thread-%d"):
728	n/a	return template % _counter()
729	n/a
730	n/a	# Active thread administration
731	n/a	_active_limbo_lock = _allocate_lock()
732	n/a	_active = {} # maps thread id to Thread object
733	n/a	_limbo = {}
734	n/a	_dangling = WeakSet()
735	n/a
736	n/a	# Main class for threads
737	n/a
738	n/a	class Thread:
739	n/a	"""A class that represents a thread of control.
740	n/a
741	n/a	This class can be safely subclassed in a limited fashion. There are two ways
742	n/a	to specify the activity: by passing a callable object to the constructor, or
743	n/a	by overriding the run() method in a subclass.
744	n/a
745	n/a	"""
746	n/a
747	n/a	_initialized = False
748	n/a	# Need to store a reference to sys.exc_info for printing
749	n/a	# out exceptions when a thread tries to use a global var. during interp.
750	n/a	# shutdown and thus raises an exception about trying to perform some
751	n/a	# operation on/with a NoneType
752	n/a	_exc_info = _sys.exc_info
753	n/a	# Keep sys.exc_clear too to clear the exception just before
754	n/a	# allowing .join() to return.
755	n/a	#XXX __exc_clear = _sys.exc_clear
756	n/a
757	n/a	def __init__(self, group=None, target=None, name=None,
758	n/a	args=(), kwargs=None, *, daemon=None):
759	n/a	"""This constructor should always be called with keyword arguments. Arguments are:
760	n/a
761	n/a	group should be None; reserved for future extension when a ThreadGroup
762	n/a	class is implemented.
763	n/a
764	n/a	target is the callable object to be invoked by the run()
765	n/a	method. Defaults to None, meaning nothing is called.
766	n/a
767	n/a	name is the thread name. By default, a unique name is constructed of
768	n/a	the form "Thread-N" where N is a small decimal number.
769	n/a
770	n/a	args is the argument tuple for the target invocation. Defaults to ().
771	n/a
772	n/a	kwargs is a dictionary of keyword arguments for the target
773	n/a	invocation. Defaults to {}.
774	n/a
775	n/a	If a subclass overrides the constructor, it must make sure to invoke
776	n/a	the base class constructor (Thread.__init__()) before doing anything
777	n/a	else to the thread.
778	n/a
779	n/a	"""
780	n/a	assert group is None, "group argument must be None for now"
781	n/a	if kwargs is None:
782	n/a	kwargs = {}
783	n/a	self._target = target
784	n/a	self._name = str(name or _newname())
785	n/a	self._args = args
786	n/a	self._kwargs = kwargs
787	n/a	if daemon is not None:
788	n/a	self._daemonic = daemon
789	n/a	else:
790	n/a	self._daemonic = current_thread().daemon
791	n/a	self._ident = None
792	n/a	self._tstate_lock = None
793	n/a	self._started = Event()
794	n/a	self._is_stopped = False
795	n/a	self._initialized = True
796	n/a	# sys.stderr is not stored in the class like
797	n/a	# sys.exc_info since it can be changed between instances
798	n/a	self._stderr = _sys.stderr
799	n/a	# For debugging and _after_fork()
800	n/a	_dangling.add(self)
801	n/a
802	n/a	def _reset_internal_locks(self, is_alive):
803	n/a	# private! Called by _after_fork() to reset our internal locks as
804	n/a	# they may be in an invalid state leading to a deadlock or crash.
805	n/a	self._started._reset_internal_locks()
806	n/a	if is_alive:
807	n/a	self._set_tstate_lock()
808	n/a	else:
809	n/a	# The thread isn't alive after fork: it doesn't have a tstate
810	n/a	# anymore.
811	n/a	self._is_stopped = True
812	n/a	self._tstate_lock = None
813	n/a
814	n/a	def __repr__(self):
815	n/a	assert self._initialized, "Thread.__init__() was not called"
816	n/a	status = "initial"
817	n/a	if self._started.is_set():
818	n/a	status = "started"
819	n/a	self.is_alive() # easy way to get ._is_stopped set when appropriate
820	n/a	if self._is_stopped:
821	n/a	status = "stopped"
822	n/a	if self._daemonic:
823	n/a	status += " daemon"
824	n/a	if self._ident is not None:
825	n/a	status += " %s" % self._ident
826	n/a	return "<%s(%s, %s)>" % (self.__class__.__name__, self._name, status)
827	n/a
828	n/a	def start(self):
829	n/a	"""Start the thread's activity.
830	n/a
831	n/a	It must be called at most once per thread object. It arranges for the
832	n/a	object's run() method to be invoked in a separate thread of control.
833	n/a
834	n/a	This method will raise a RuntimeError if called more than once on the
835	n/a	same thread object.
836	n/a
837	n/a	"""
838	n/a	if not self._initialized:
839	n/a	raise RuntimeError("thread.__init__() not called")
840	n/a
841	n/a	if self._started.is_set():
842	n/a	raise RuntimeError("threads can only be started once")
843	n/a	with _active_limbo_lock:
844	n/a	_limbo[self] = self
845	n/a	try:
846	n/a	_start_new_thread(self._bootstrap, ())
847	n/a	except Exception:
848	n/a	with _active_limbo_lock:
849	n/a	del _limbo[self]
850	n/a	raise
851	n/a	self._started.wait()
852	n/a
853	n/a	def run(self):
854	n/a	"""Method representing the thread's activity.
855	n/a
856	n/a	You may override this method in a subclass. The standard run() method
857	n/a	invokes the callable object passed to the object's constructor as the
858	n/a	target argument, if any, with sequential and keyword arguments taken
859	n/a	from the args and kwargs arguments, respectively.
860	n/a
861	n/a	"""
862	n/a	try:
863	n/a	if self._target:
864	n/a	self._target(self._args, *self._kwargs)
865	n/a	finally:
866	n/a	# Avoid a refcycle if the thread is running a function with
867	n/a	# an argument that has a member that points to the thread.
868	n/a	del self._target, self._args, self._kwargs
869	n/a
870	n/a	def _bootstrap(self):
871	n/a	# Wrapper around the real bootstrap code that ignores
872	n/a	# exceptions during interpreter cleanup. Those typically
873	n/a	# happen when a daemon thread wakes up at an unfortunate
874	n/a	# moment, finds the world around it destroyed, and raises some
875	n/a	# random exception *** while trying to report the exception in
876	n/a	# _bootstrap_inner() below ***. Those random exceptions
877	n/a	# don't help anybody, and they confuse users, so we suppress
878	n/a	# them. We suppress them only when it appears that the world
879	n/a	# indeed has already been destroyed, so that exceptions in
880	n/a	# _bootstrap_inner() during normal business hours are properly
881	n/a	# reported. Also, we only suppress them for daemonic threads;
882	n/a	# if a non-daemonic encounters this, something else is wrong.
883	n/a	try:
884	n/a	self._bootstrap_inner()
885	n/a	except:
886	n/a	if self._daemonic and _sys is None:
887	n/a	return
888	n/a	raise
889	n/a
890	n/a	def _set_ident(self):
891	n/a	self._ident = get_ident()
892	n/a
893	n/a	def _set_tstate_lock(self):
894	n/a	"""
895	n/a	Set a lock object which will be released by the interpreter when
896	n/a	the underlying thread state (see pystate.h) gets deleted.
897	n/a	"""
898	n/a	self._tstate_lock = _set_sentinel()
899	n/a	self._tstate_lock.acquire()
900	n/a
901	n/a	def _bootstrap_inner(self):
902	n/a	try:
903	n/a	self._set_ident()
904	n/a	self._set_tstate_lock()
905	n/a	self._started.set()
906	n/a	with _active_limbo_lock:
907	n/a	_active[self._ident] = self
908	n/a	del _limbo[self]
909	n/a
910	n/a	if _trace_hook:
911	n/a	_sys.settrace(_trace_hook)
912	n/a	if _profile_hook:
913	n/a	_sys.setprofile(_profile_hook)
914	n/a
915	n/a	try:
916	n/a	self.run()
917	n/a	except SystemExit:
918	n/a	pass
919	n/a	except:
920	n/a	# If sys.stderr is no more (most likely from interpreter
921	n/a	# shutdown) use self._stderr. Otherwise still use sys (as in
922	n/a	# _sys) in case sys.stderr was redefined since the creation of
923	n/a	# self.
924	n/a	if _sys and _sys.stderr is not None:
925	n/a	print("Exception in thread %s:\n%s" %
926	n/a	(self.name, _format_exc()), file=_sys.stderr)
927	n/a	elif self._stderr is not None:
928	n/a	# Do the best job possible w/o a huge amt. of code to
929	n/a	# approximate a traceback (code ideas from
930	n/a	# Lib/traceback.py)
931	n/a	exc_type, exc_value, exc_tb = self._exc_info()
932	n/a	try:
933	n/a	print((
934	n/a	"Exception in thread " + self.name +
935	n/a	" (most likely raised during interpreter shutdown):"), file=self._stderr)
936	n/a	print((
937	n/a	"Traceback (most recent call last):"), file=self._stderr)
938	n/a	while exc_tb:
939	n/a	print((
940	n/a	' File "%s", line %s, in %s' %
941	n/a	(exc_tb.tb_frame.f_code.co_filename,
942	n/a	exc_tb.tb_lineno,
943	n/a	exc_tb.tb_frame.f_code.co_name)), file=self._stderr)
944	n/a	exc_tb = exc_tb.tb_next
945	n/a	print(("%s: %s" % (exc_type, exc_value)), file=self._stderr)
946	n/a	# Make sure that exc_tb gets deleted since it is a memory
947	n/a	# hog; deleting everything else is just for thoroughness
948	n/a	finally:
949	n/a	del exc_type, exc_value, exc_tb
950	n/a	finally:
951	n/a	# Prevent a race in
952	n/a	# test_threading.test_no_refcycle_through_target when
953	n/a	# the exception keeps the target alive past when we
954	n/a	# assert that it's dead.
955	n/a	#XXX self._exc_clear()
956	n/a	pass
957	n/a	finally:
958	n/a	with _active_limbo_lock:
959	n/a	try:
960	n/a	# We don't call self._delete() because it also
961	n/a	# grabs _active_limbo_lock.
962	n/a	del _active[get_ident()]
963	n/a	except:
964	n/a	pass
965	n/a
966	n/a	def _stop(self):
967	n/a	# After calling ._stop(), .is_alive() returns False and .join() returns
968	n/a	# immediately. ._tstate_lock must be released before calling ._stop().
969	n/a	#
970	n/a	# Normal case: C code at the end of the thread's life
971	n/a	# (release_sentinel in _threadmodule.c) releases ._tstate_lock, and
972	n/a	# that's detected by our ._wait_for_tstate_lock(), called by .join()
973	n/a	# and .is_alive(). Any number of threads _may_ call ._stop()
974	n/a	# simultaneously (for example, if multiple threads are blocked in
975	n/a	# .join() calls), and they're not serialized. That's harmless -
976	n/a	# they'll just make redundant rebindings of ._is_stopped and
977	n/a	# ._tstate_lock. Obscure: we rebind ._tstate_lock last so that the
978	n/a	# "assert self._is_stopped" in ._wait_for_tstate_lock() always works
979	n/a	# (the assert is executed only if ._tstate_lock is None).
980	n/a	#
981	n/a	# Special case: _main_thread releases ._tstate_lock via this
982	n/a	# module's _shutdown() function.
983	n/a	lock = self._tstate_lock
984	n/a	if lock is not None:
985	n/a	assert not lock.locked()
986	n/a	self._is_stopped = True
987	n/a	self._tstate_lock = None
988	n/a
989	n/a	def _delete(self):
990	n/a	"Remove current thread from the dict of currently running threads."
991	n/a
992	n/a	# Notes about running with _dummy_thread:
993	n/a	#
994	n/a	# Must take care to not raise an exception if _dummy_thread is being
995	n/a	# used (and thus this module is being used as an instance of
996	n/a	# dummy_threading). _dummy_thread.get_ident() always returns -1 since
997	n/a	# there is only one thread if _dummy_thread is being used. Thus
998	n/a	# len(_active) is always <= 1 here, and any Thread instance created
999	n/a	# overwrites the (if any) thread currently registered in _active.
1000	n/a	#
1001	n/a	# An instance of _MainThread is always created by 'threading'. This
1002	n/a	# gets overwritten the instant an instance of Thread is created; both
1003	n/a	# threads return -1 from _dummy_thread.get_ident() and thus have the
1004	n/a	# same key in the dict. So when the _MainThread instance created by
1005	n/a	# 'threading' tries to clean itself up when atexit calls this method
1006	n/a	# it gets a KeyError if another Thread instance was created.
1007	n/a	#
1008	n/a	# This all means that KeyError from trying to delete something from
1009	n/a	# _active if dummy_threading is being used is a red herring. But
1010	n/a	# since it isn't if dummy_threading is not being used then don't
1011	n/a	# hide the exception.
1012	n/a
1013	n/a	try:
1014	n/a	with _active_limbo_lock:
1015	n/a	del _active[get_ident()]
1016	n/a	# There must not be any python code between the previous line
1017	n/a	# and after the lock is released. Otherwise a tracing function
1018	n/a	# could try to acquire the lock again in the same thread, (in
1019	n/a	# current_thread()), and would block.
1020	n/a	except KeyError:
1021	n/a	if 'dummy_threading' not in _sys.modules:
1022	n/a	raise
1023	n/a
1024	n/a	def join(self, timeout=None):
1025	n/a	"""Wait until the thread terminates.
1026	n/a
1027	n/a	This blocks the calling thread until the thread whose join() method is
1028	n/a	called terminates -- either normally or through an unhandled exception
1029	n/a	or until the optional timeout occurs.
1030	n/a
1031	n/a	When the timeout argument is present and not None, it should be a
1032	n/a	floating point number specifying a timeout for the operation in seconds
1033	n/a	(or fractions thereof). As join() always returns None, you must call
1034	n/a	isAlive() after join() to decide whether a timeout happened -- if the
1035	n/a	thread is still alive, the join() call timed out.
1036	n/a
1037	n/a	When the timeout argument is not present or None, the operation will
1038	n/a	block until the thread terminates.
1039	n/a
1040	n/a	A thread can be join()ed many times.
1041	n/a
1042	n/a	join() raises a RuntimeError if an attempt is made to join the current
1043	n/a	thread as that would cause a deadlock. It is also an error to join() a
1044	n/a	thread before it has been started and attempts to do so raises the same
1045	n/a	exception.
1046	n/a
1047	n/a	"""
1048	n/a	if not self._initialized:
1049	n/a	raise RuntimeError("Thread.__init__() not called")
1050	n/a	if not self._started.is_set():
1051	n/a	raise RuntimeError("cannot join thread before it is started")
1052	n/a	if self is current_thread():
1053	n/a	raise RuntimeError("cannot join current thread")
1054	n/a
1055	n/a	if timeout is None:
1056	n/a	self._wait_for_tstate_lock()
1057	n/a	else:
1058	n/a	# the behavior of a negative timeout isn't documented, but
1059	n/a	# historically .join(timeout=x) for x<0 has acted as if timeout=0
1060	n/a	self._wait_for_tstate_lock(timeout=max(timeout, 0))
1061	n/a
1062	n/a	def _wait_for_tstate_lock(self, block=True, timeout=-1):
1063	n/a	# Issue #18808: wait for the thread state to be gone.
1064	n/a	# At the end of the thread's life, after all knowledge of the thread
1065	n/a	# is removed from C data structures, C code releases our _tstate_lock.
1066	n/a	# This method passes its arguments to _tstate_lock.acquire().
1067	n/a	# If the lock is acquired, the C code is done, and self._stop() is
1068	n/a	# called. That sets ._is_stopped to True, and ._tstate_lock to None.
1069	n/a	lock = self._tstate_lock
1070	n/a	if lock is None: # already determined that the C code is done
1071	n/a	assert self._is_stopped
1072	n/a	elif lock.acquire(block, timeout):
1073	n/a	lock.release()
1074	n/a	self._stop()
1075	n/a
1076	n/a	@property
1077	n/a	def name(self):
1078	n/a	"""A string used for identification purposes only.
1079	n/a
1080	n/a	It has no semantics. Multiple threads may be given the same name. The
1081	n/a	initial name is set by the constructor.
1082	n/a
1083	n/a	"""
1084	n/a	assert self._initialized, "Thread.__init__() not called"
1085	n/a	return self._name
1086	n/a
1087	n/a	@name.setter
1088	n/a	def name(self, name):
1089	n/a	assert self._initialized, "Thread.__init__() not called"
1090	n/a	self._name = str(name)
1091	n/a
1092	n/a	@property
1093	n/a	def ident(self):
1094	n/a	"""Thread identifier of this thread or None if it has not been started.
1095	n/a
1096	n/a	This is a nonzero integer. See the thread.get_ident() function. Thread
1097	n/a	identifiers may be recycled when a thread exits and another thread is
1098	n/a	created. The identifier is available even after the thread has exited.
1099	n/a
1100	n/a	"""
1101	n/a	assert self._initialized, "Thread.__init__() not called"
1102	n/a	return self._ident
1103	n/a
1104	n/a	def is_alive(self):
1105	n/a	"""Return whether the thread is alive.
1106	n/a
1107	n/a	This method returns True just before the run() method starts until just
1108	n/a	after the run() method terminates. The module function enumerate()
1109	n/a	returns a list of all alive threads.
1110	n/a
1111	n/a	"""
1112	n/a	assert self._initialized, "Thread.__init__() not called"
1113	n/a	if self._is_stopped or not self._started.is_set():
1114	n/a	return False
1115	n/a	self._wait_for_tstate_lock(False)
1116	n/a	return not self._is_stopped
1117	n/a
1118	n/a	isAlive = is_alive
1119	n/a
1120	n/a	@property
1121	n/a	def daemon(self):
1122	n/a	"""A boolean value indicating whether this thread is a daemon thread.
1123	n/a
1124	n/a	This must be set before start() is called, otherwise RuntimeError is
1125	n/a	raised. Its initial value is inherited from the creating thread; the
1126	n/a	main thread is not a daemon thread and therefore all threads created in
1127	n/a	the main thread default to daemon = False.
1128	n/a
1129	n/a	The entire Python program exits when no alive non-daemon threads are
1130	n/a	left.
1131	n/a
1132	n/a	"""
1133	n/a	assert self._initialized, "Thread.__init__() not called"
1134	n/a	return self._daemonic
1135	n/a
1136	n/a	@daemon.setter
1137	n/a	def daemon(self, daemonic):
1138	n/a	if not self._initialized:
1139	n/a	raise RuntimeError("Thread.__init__() not called")
1140	n/a	if self._started.is_set():
1141	n/a	raise RuntimeError("cannot set daemon status of active thread")
1142	n/a	self._daemonic = daemonic
1143	n/a
1144	n/a	def isDaemon(self):
1145	n/a	return self.daemon
1146	n/a
1147	n/a	def setDaemon(self, daemonic):
1148	n/a	self.daemon = daemonic
1149	n/a
1150	n/a	def getName(self):
1151	n/a	return self.name
1152	n/a
1153	n/a	def setName(self, name):
1154	n/a	self.name = name
1155	n/a
1156	n/a	# The timer class was contributed by Itamar Shtull-Trauring
1157	n/a
1158	n/a	class Timer(Thread):
1159	n/a	"""Call a function after a specified number of seconds:
1160	n/a
1161	n/a	t = Timer(30.0, f, args=None, kwargs=None)
1162	n/a	t.start()
1163	n/a	t.cancel() # stop the timer's action if it's still waiting
1164	n/a
1165	n/a	"""
1166	n/a
1167	n/a	def __init__(self, interval, function, args=None, kwargs=None):
1168	n/a	Thread.__init__(self)
1169	n/a	self.interval = interval
1170	n/a	self.function = function
1171	n/a	self.args = args if args is not None else []
1172	n/a	self.kwargs = kwargs if kwargs is not None else {}
1173	n/a	self.finished = Event()
1174	n/a
1175	n/a	def cancel(self):
1176	n/a	"""Stop the timer if it hasn't finished yet."""
1177	n/a	self.finished.set()
1178	n/a
1179	n/a	def run(self):
1180	n/a	self.finished.wait(self.interval)
1181	n/a	if not self.finished.is_set():
1182	n/a	self.function(self.args, *self.kwargs)
1183	n/a	self.finished.set()
1184	n/a
1185	n/a	# Special thread class to represent the main thread
1186	n/a	# This is garbage collected through an exit handler
1187	n/a
1188	n/a	class _MainThread(Thread):
1189	n/a
1190	n/a	def __init__(self):
1191	n/a	Thread.__init__(self, name="MainThread", daemon=False)
1192	n/a	self._set_tstate_lock()
1193	n/a	self._started.set()
1194	n/a	self._set_ident()
1195	n/a	with _active_limbo_lock:
1196	n/a	_active[self._ident] = self
1197	n/a
1198	n/a
1199	n/a	# Dummy thread class to represent threads not started here.
1200	n/a	# These aren't garbage collected when they die, nor can they be waited for.
1201	n/a	# If they invoke anything in threading.py that calls current_thread(), they
1202	n/a	# leave an entry in the _active dict forever after.
1203	n/a	# Their purpose is to return something from current_thread().
1204	n/a	# They are marked as daemon threads so we won't wait for them
1205	n/a	# when we exit (conform previous semantics).
1206	n/a
1207	n/a	class _DummyThread(Thread):
1208	n/a
1209	n/a	def __init__(self):
1210	n/a	Thread.__init__(self, name=_newname("Dummy-%d"), daemon=True)
1211	n/a
1212	n/a	self._started.set()
1213	n/a	self._set_ident()
1214	n/a	with _active_limbo_lock:
1215	n/a	_active[self._ident] = self
1216	n/a
1217	n/a	def _stop(self):
1218	n/a	pass
1219	n/a
1220	n/a	def join(self, timeout=None):
1221	n/a	assert False, "cannot join a dummy thread"
1222	n/a
1223	n/a
1224	n/a	# Global API functions
1225	n/a
1226	n/a	def current_thread():
1227	n/a	"""Return the current Thread object, corresponding to the caller's thread of control.
1228	n/a
1229	n/a	If the caller's thread of control was not created through the threading
1230	n/a	module, a dummy thread object with limited functionality is returned.
1231	n/a
1232	n/a	"""
1233	n/a	try:
1234	n/a	return _active[get_ident()]
1235	n/a	except KeyError:
1236	n/a	return _DummyThread()
1237	n/a
1238	n/a	currentThread = current_thread
1239	n/a
1240	n/a	def active_count():
1241	n/a	"""Return the number of Thread objects currently alive.
1242	n/a
1243	n/a	The returned count is equal to the length of the list returned by
1244	n/a	enumerate().
1245	n/a
1246	n/a	"""
1247	n/a	with _active_limbo_lock:
1248	n/a	return len(_active) + len(_limbo)
1249	n/a
1250	n/a	activeCount = active_count
1251	n/a
1252	n/a	def _enumerate():
1253	n/a	# Same as enumerate(), but without the lock. Internal use only.
1254	n/a	return list(_active.values()) + list(_limbo.values())
1255	n/a
1256	n/a	def enumerate():
1257	n/a	"""Return a list of all Thread objects currently alive.
1258	n/a
1259	n/a	The list includes daemonic threads, dummy thread objects created by
1260	n/a	current_thread(), and the main thread. It excludes terminated threads and
1261	n/a	threads that have not yet been started.
1262	n/a
1263	n/a	"""
1264	n/a	with _active_limbo_lock:
1265	n/a	return list(_active.values()) + list(_limbo.values())
1266	n/a
1267	n/a	from _thread import stack_size
1268	n/a
1269	n/a	# Create the main thread object,
1270	n/a	# and make it available for the interpreter
1271	n/a	# (Py_Main) as threading._shutdown.
1272	n/a
1273	n/a	_main_thread = _MainThread()
1274	n/a
1275	n/a	def _shutdown():
1276	n/a	# Obscure: other threads may be waiting to join _main_thread. That's
1277	n/a	# dubious, but some code does it. We can't wait for C code to release
1278	n/a	# the main thread's tstate_lock - that won't happen until the interpreter
1279	n/a	# is nearly dead. So we release it here. Note that just calling _stop()
1280	n/a	# isn't enough: other threads may already be waiting on _tstate_lock.
1281	n/a	tlock = _main_thread._tstate_lock
1282	n/a	# The main thread isn't finished yet, so its thread state lock can't have
1283	n/a	# been released.
1284	n/a	assert tlock is not None
1285	n/a	assert tlock.locked()
1286	n/a	tlock.release()
1287	n/a	_main_thread._stop()
1288	n/a	t = _pickSomeNonDaemonThread()
1289	n/a	while t:
1290	n/a	t.join()
1291	n/a	t = _pickSomeNonDaemonThread()
1292	n/a	_main_thread._delete()
1293	n/a
1294	n/a	def _pickSomeNonDaemonThread():
1295	n/a	for t in enumerate():
1296	n/a	if not t.daemon and t.is_alive():
1297	n/a	return t
1298	n/a	return None
1299	n/a
1300	n/a	def main_thread():
1301	n/a	"""Return the main thread object.
1302	n/a
1303	n/a	In normal conditions, the main thread is the thread from which the
1304	n/a	Python interpreter was started.
1305	n/a	"""
1306	n/a	return _main_thread
1307	n/a
1308	n/a	# get thread-local implementation, either from the thread
1309	n/a	# module, or from the python fallback
1310	n/a
1311	n/a	try:
1312	n/a	from _thread import _local as local
1313	n/a	except ImportError:
1314	n/a	from _threading_local import local
1315	n/a
1316	n/a
1317	n/a	def _after_fork():
1318	n/a	# This function is called by Python/ceval.c:PyEval_ReInitThreads which
1319	n/a	# is called from PyOS_AfterFork. Here we cleanup threading module state
1320	n/a	# that should not exist after a fork.
1321	n/a
1322	n/a	# Reset _active_limbo_lock, in case we forked while the lock was held
1323	n/a	# by another (non-forked) thread. http://bugs.python.org/issue874900
1324	n/a	global _active_limbo_lock, _main_thread
1325	n/a	_active_limbo_lock = _allocate_lock()
1326	n/a
1327	n/a	# fork() only copied the current thread; clear references to others.
1328	n/a	new_active = {}
1329	n/a	current = current_thread()
1330	n/a	_main_thread = current
1331	n/a	with _active_limbo_lock:
1332	n/a	# Dangling thread instances must still have their locks reset,
1333	n/a	# because someone may join() them.
1334	n/a	threads = set(_enumerate())
1335	n/a	threads.update(_dangling)
1336	n/a	for thread in threads:
1337	n/a	# Any lock/condition variable may be currently locked or in an
1338	n/a	# invalid state, so we reinitialize them.
1339	n/a	if thread is current:
1340	n/a	# There is only one active thread. We reset the ident to
1341	n/a	# its new value since it can have changed.
1342	n/a	thread._reset_internal_locks(True)
1343	n/a	ident = get_ident()
1344	n/a	thread._ident = ident
1345	n/a	new_active[ident] = thread
1346	n/a	else:
1347	n/a	# All the others are already stopped.
1348	n/a	thread._reset_internal_locks(False)
1349	n/a	thread._stop()
1350	n/a
1351	n/a	_limbo.clear()
1352	n/a	_active.clear()
1353	n/a	_active.update(new_active)
1354	n/a	assert len(_active) == 1