1
2
3 """Thread-local objects
4
5 (Note that this module provides a Python version of thread
6 threading.local class. Depending on the version of Python you're
7 using, there may be a faster one available. You should always import
8 the local class from threading.)
9
10 Thread-local objects support the management of thread-local data.
11 If you have data that you want to be local to a thread, simply create
12 a thread-local object and use its attributes:
13
14 >>> mydata = local()
15 >>> mydata.number = 42
16 >>> mydata.number
17 42
18
19 You can also access the local-object's dictionary:
20
21 >>> mydata.__dict__
22 {'number': 42}
23 >>> mydata.__dict__.setdefault('widgets', [])
24 []
25 >>> mydata.widgets
26 []
27
28 What's important about thread-local objects is that their data are
29 local to a thread. If we access the data in a different thread:
30
31 >>> log = []
32 >>> def f():
33 ... items = mydata.__dict__.items()
34 ... items.sort()
35 ... log.append(items)
36 ... mydata.number = 11
37 ... log.append(mydata.number)
38
39 >>> import threading
40 >>> thread = threading.Thread(target=f)
41 >>> thread.start()
42 >>> thread.join()
43 >>> log
44 [[], 11]
45
46 we get different data. Furthermore, changes made in the other thread
47 don't affect data seen in this thread:
48
49 >>> mydata.number
50 42
51
52 Of course, values you get from a local object, including a __dict__
53 attribute, are for whatever thread was current at the time the
54 attribute was read. For that reason, you generally don't want to save
55 these values across threads, as they apply only to the thread they
56 came from.
57
58 You can create custom local objects by subclassing the local class:
59
60 >>> class MyLocal(local):
61 ... number = 2
62 ... initialized = False
63 ... def __init__(self, **kw):
64 ... if self.initialized:
65 ... raise SystemError('__init__ called too many times')
66 ... self.initialized = True
67 ... self.__dict__.update(kw)
68 ... def squared(self):
69 ... return self.number ** 2
70
71 This can be useful to support default values, methods and
72 initialization. Note that if you define an __init__ method, it will be
73 called each time the local object is used in a separate thread. This
74 is necessary to initialize each thread's dictionary.
75
76 Now if we create a local object:
77
78 >>> mydata = MyLocal(color='red')
79
80 Now we have a default number:
81
82 >>> mydata.number
83 2
84
85 an initial color:
86
87 >>> mydata.color
88 'red'
89 >>> del mydata.color
90
91 And a method that operates on the data:
92
93 >>> mydata.squared()
94 4
95
96 As before, we can access the data in a separate thread:
97
98 >>> log = []
99 >>> thread = threading.Thread(target=f)
100 >>> thread.start()
101 >>> thread.join()
102 >>> log
103 [[('color', 'red'), ('initialized', True)], 11]
104
105 without affecting this thread's data:
106
107 >>> mydata.number
108 2
109 >>> mydata.color
110 Traceback (most recent call last):
111 ...
112 AttributeError: 'MyLocal' object has no attribute 'color'
113
114 Note that subclasses can define slots, but they are not thread
115 local. They are shared across threads:
116
117 >>> class MyLocal(local):
118 ... __slots__ = 'number'
119
120 >>> mydata = MyLocal()
121 >>> mydata.number = 42
122 >>> mydata.color = 'red'
123
124 So, the separate thread:
125
126 >>> thread = threading.Thread(target=f)
127 >>> thread.start()
128 >>> thread.join()
129
130 affects what we see:
131
132 >>> mydata.number
133 11
134
135 >>> del mydata
136 """
137
138
139
141 __slots__ = '_local__key', '_local__args', '_local__lock'
142
144 self = object.__new__(cls)
145 key = 'thread.local.' + str(id(self))
146 object.__setattr__(self, '_local__key', key)
147 object.__setattr__(self, '_local__args', (args, kw))
148 object.__setattr__(self, '_local__lock', RLock())
149
150 if args or kw and (cls.__init__ is object.__init__):
151 raise TypeError("Initialization arguments are not supported")
152
153
154
155
156 dict = object.__getattribute__(self, '__dict__')
157 currentThread().__dict__[key] = dict
158
159 return self
160
177
179
188
197
206
207
235
236 return __del__
237 __del__ = __del__()
238
239 from threading import currentThread, enumerate, RLock
240