Python code coverage for Lib/_threading_local.py

#	count	content
1	n/a	"""Thread-local objects.
2	n/a
3	n/a	(Note that this module provides a Python version of the threading.local
4	n/a	class. Depending on the version of Python you're using, there may be a
5	n/a	faster one available. You should always import the `local` class from
6	n/a	`threading`.)
7	n/a
8	n/a	Thread-local objects support the management of thread-local data.
9	n/a	If you have data that you want to be local to a thread, simply create
10	n/a	a thread-local object and use its attributes:
11	n/a
12	n/a	>>> mydata = local()
13	n/a	>>> mydata.number = 42
14	n/a	>>> mydata.number
15	n/a	42
16	n/a
17	n/a	You can also access the local-object's dictionary:
18	n/a
19	n/a	>>> mydata.__dict__
20	n/a	{'number': 42}
21	n/a	>>> mydata.__dict__.setdefault('widgets', [])
22	n/a	[]
23	n/a	>>> mydata.widgets
24	n/a	[]
25	n/a
26	n/a	What's important about thread-local objects is that their data are
27	n/a	local to a thread. If we access the data in a different thread:
28	n/a
29	n/a	>>> log = []
30	n/a	>>> def f():
31	n/a	... items = sorted(mydata.__dict__.items())
32	n/a	... log.append(items)
33	n/a	... mydata.number = 11
34	n/a	... log.append(mydata.number)
35	n/a
36	n/a	>>> import threading
37	n/a	>>> thread = threading.Thread(target=f)
38	n/a	>>> thread.start()
39	n/a	>>> thread.join()
40	n/a	>>> log
41	n/a	[[], 11]
42	n/a
43	n/a	we get different data. Furthermore, changes made in the other thread
44	n/a	don't affect data seen in this thread:
45	n/a
46	n/a	>>> mydata.number
47	n/a	42
48	n/a
49	n/a	Of course, values you get from a local object, including a __dict__
50	n/a	attribute, are for whatever thread was current at the time the
51	n/a	attribute was read. For that reason, you generally don't want to save
52	n/a	these values across threads, as they apply only to the thread they
53	n/a	came from.
54	n/a
55	n/a	You can create custom local objects by subclassing the local class:
56	n/a
57	n/a	>>> class MyLocal(local):
58	n/a	... number = 2
59	n/a	... initialized = False
60	n/a	... def __init__(self, **kw):
61	n/a	... if self.initialized:
62	n/a	... raise SystemError('__init__ called too many times')
63	n/a	... self.initialized = True
64	n/a	... self.__dict__.update(kw)
65	n/a	... def squared(self):
66	n/a	... return self.number ** 2
67	n/a
68	n/a	This can be useful to support default values, methods and
69	n/a	initialization. Note that if you define an __init__ method, it will be
70	n/a	called each time the local object is used in a separate thread. This
71	n/a	is necessary to initialize each thread's dictionary.
72	n/a
73	n/a	Now if we create a local object:
74	n/a
75	n/a	>>> mydata = MyLocal(color='red')
76	n/a
77	n/a	Now we have a default number:
78	n/a
79	n/a	>>> mydata.number
80	n/a	2
81	n/a
82	n/a	an initial color:
83	n/a
84	n/a	>>> mydata.color
85	n/a	'red'
86	n/a	>>> del mydata.color
87	n/a
88	n/a	And a method that operates on the data:
89	n/a
90	n/a	>>> mydata.squared()
91	n/a	4
92	n/a
93	n/a	As before, we can access the data in a separate thread:
94	n/a
95	n/a	>>> log = []
96	n/a	>>> thread = threading.Thread(target=f)
97	n/a	>>> thread.start()
98	n/a	>>> thread.join()
99	n/a	>>> log
100	n/a	[[('color', 'red'), ('initialized', True)], 11]
101	n/a
102	n/a	without affecting this thread's data:
103	n/a
104	n/a	>>> mydata.number
105	n/a	2
106	n/a	>>> mydata.color
107	n/a	Traceback (most recent call last):
108	n/a	...
109	n/a	AttributeError: 'MyLocal' object has no attribute 'color'
110	n/a
111	n/a	Note that subclasses can define slots, but they are not thread
112	n/a	local. They are shared across threads:
113	n/a
114	n/a	>>> class MyLocal(local):
115	n/a	... __slots__ = 'number'
116	n/a
117	n/a	>>> mydata = MyLocal()
118	n/a	>>> mydata.number = 42
119	n/a	>>> mydata.color = 'red'
120	n/a
121	n/a	So, the separate thread:
122	n/a
123	n/a	>>> thread = threading.Thread(target=f)
124	n/a	>>> thread.start()
125	n/a	>>> thread.join()
126	n/a
127	n/a	affects what we see:
128	n/a
129	n/a	>>> mydata.number
130	n/a	11
131	n/a
132	n/a	>>> del mydata
133	n/a	"""
134	n/a
135	n/a	from weakref import ref
136	n/a	from contextlib import contextmanager
137	n/a
138	n/a	__all__ = ["local"]
139	n/a
140	n/a	# We need to use objects from the threading module, but the threading
141	n/a	# module may also want to use our `local` class, if support for locals
142	n/a	# isn't compiled in to the `thread` module. This creates potential problems
143	n/a	# with circular imports. For that reason, we don't import `threading`
144	n/a	# until the bottom of this file (a hack sufficient to worm around the
145	n/a	# potential problems). Note that all platforms on CPython do have support
146	n/a	# for locals in the `thread` module, and there is no circular import problem
147	n/a	# then, so problems introduced by fiddling the order of imports here won't
148	n/a	# manifest.
149	n/a
150	n/a	class _localimpl:
151	n/a	"""A class managing thread-local dicts"""
152	n/a	__slots__ = 'key', 'dicts', 'localargs', 'locallock', '__weakref__'
153	n/a
154	n/a	def __init__(self):
155	n/a	# The key used in the Thread objects' attribute dicts.
156	n/a	# We keep it a string for speed but make it unlikely to clash with
157	n/a	# a "real" attribute.
158	n/a	self.key = '_threading_local._localimpl.' + str(id(self))
159	n/a	# { id(Thread) -> (ref(Thread), thread-local dict) }
160	n/a	self.dicts = {}
161	n/a
162	n/a	def get_dict(self):
163	n/a	"""Return the dict for the current thread. Raises KeyError if none
164	n/a	defined."""
165	n/a	thread = current_thread()
166	n/a	return self.dicts[id(thread)][1]
167	n/a
168	n/a	def create_dict(self):
169	n/a	"""Create a new dict for the current thread, and return it."""
170	n/a	localdict = {}
171	n/a	key = self.key
172	n/a	thread = current_thread()
173	n/a	idt = id(thread)
174	n/a	def local_deleted(_, key=key):
175	n/a	# When the localimpl is deleted, remove the thread attribute.
176	n/a	thread = wrthread()
177	n/a	if thread is not None:
178	n/a	del thread.__dict__[key]
179	n/a	def thread_deleted(_, idt=idt):
180	n/a	# When the thread is deleted, remove the local dict.
181	n/a	# Note that this is suboptimal if the thread object gets
182	n/a	# caught in a reference loop. We would like to be called
183	n/a	# as soon as the OS-level thread ends instead.
184	n/a	local = wrlocal()
185	n/a	if local is not None:
186	n/a	dct = local.dicts.pop(idt)
187	n/a	wrlocal = ref(self, local_deleted)
188	n/a	wrthread = ref(thread, thread_deleted)
189	n/a	thread.__dict__[key] = wrlocal
190	n/a	self.dicts[idt] = wrthread, localdict
191	n/a	return localdict
192	n/a
193	n/a
194	n/a	@contextmanager
195	n/a	def _patch(self):
196	n/a	impl = object.__getattribute__(self, '_local__impl')
197	n/a	try:
198	n/a	dct = impl.get_dict()
199	n/a	except KeyError:
200	n/a	dct = impl.create_dict()
201	n/a	args, kw = impl.localargs
202	n/a	self.__init__(args, *kw)
203	n/a	with impl.locallock:
204	n/a	object.__setattr__(self, '__dict__', dct)
205	n/a	yield
206	n/a
207	n/a
208	n/a	class local:
209	n/a	__slots__ = '_local__impl', '__dict__'
210	n/a
211	n/a	def __new__(cls, args, *kw):
212	n/a	if (args or kw) and (cls.__init__ is object.__init__):
213	n/a	raise TypeError("Initialization arguments are not supported")
214	n/a	self = object.__new__(cls)
215	n/a	impl = _localimpl()
216	n/a	impl.localargs = (args, kw)
217	n/a	impl.locallock = RLock()
218	n/a	object.__setattr__(self, '_local__impl', impl)
219	n/a	# We need to create the thread dict in anticipation of
220	n/a	# __init__ being called, to make sure we don't call it
221	n/a	# again ourselves.
222	n/a	impl.create_dict()
223	n/a	return self
224	n/a
225	n/a	def __getattribute__(self, name):
226	n/a	with _patch(self):
227	n/a	return object.__getattribute__(self, name)
228	n/a
229	n/a	def __setattr__(self, name, value):
230	n/a	if name == '__dict__':
231	n/a	raise AttributeError(
232	n/a	"%r object attribute '__dict__' is read-only"
233	n/a	% self.__class__.__name__)
234	n/a	with _patch(self):
235	n/a	return object.__setattr__(self, name, value)
236	n/a
237	n/a	def __delattr__(self, name):
238	n/a	if name == '__dict__':
239	n/a	raise AttributeError(
240	n/a	"%r object attribute '__dict__' is read-only"
241	n/a	% self.__class__.__name__)
242	n/a	with _patch(self):
243	n/a	return object.__delattr__(self, name)
244	n/a
245	n/a
246	n/a	from threading import current_thread, RLock