|
111
|
1 This file describes in little detail the modifications to the
|
|
|
2 Objective-C runtime needed to make it thread safe.
|
|
|
3
|
|
|
4 First off, kudos to Galen Hunt who is the author of this great work.
|
|
|
5
|
|
|
6 If you have an comments or just want to know where to
|
|
|
7 send me money to express your undying gratitude for threading the
|
|
|
8 Objective-C runtime you can reach Galen at:
|
|
|
9
|
|
|
10 gchunt@cs.rochester.edu
|
|
|
11
|
|
|
12 Any questions, comments, bug reports, etc. should send email either to the
|
|
|
13 GCC bug account or to:
|
|
|
14
|
|
|
15 Scott Christley <scottc@net-community.com>
|
|
|
16
|
|
|
17 * Sarray Threading:
|
|
|
18
|
|
|
19 The most critical component of the Objective-C runtime is the sparse array
|
|
|
20 structure (sarray). Sarrays store object selectors and implementations.
|
|
|
21 Following in the tradition of the Objective-C runtime, my threading
|
|
|
22 support assumes that fast message dispatching is far more important
|
|
|
23 than *ANY* and *ALL* other operations. The message dispatching thus
|
|
|
24 uses *NO* locks on any kind. In fact, if you look in sarray.h, you
|
|
|
25 will notice that the message dispatching has not been modified.
|
|
|
26 Instead, I have modified the sarray management functions so that all
|
|
|
27 updates to the sarray data structure can be made in parallel will
|
|
|
28 message dispatching.
|
|
|
29
|
|
|
30 To support concurrent message dispatching, no dynamically allocated
|
|
|
31 sarray data structures are freed while more than one thread is
|
|
|
32 operational. Sarray data structures that are no longer in use are
|
|
|
33 kept in a linked list of garbage and are released whenever the program
|
|
|
34 is operating with a single thread. The programmer can also flush the
|
|
|
35 garbage list by calling sarray_remove_garbage when the programmer can
|
|
|
36 ensure that no message dispatching is taking place concurrently. The
|
|
|
37 amount of un-reclaimed sarray garbage should normally be extremely
|
|
|
38 small in a real program as sarray structures are freed only when using
|
|
|
39 the "poseAs" functionality and early in program initialization, which
|
|
|
40 normally occurs while the program is single threaded.
|
|
|
41
|
|
|
42 ******************************************************************************
|
|
|
43 * Static Variables:
|
|
|
44
|
|
|
45 The following variables are either statically or globally defined. This list
|
|
|
46 does not include variables which are internal to implementation dependent
|
|
|
47 versions of thread-*.c.
|
|
|
48
|
|
|
49 The following threading designations are used:
|
|
|
50 SAFE : Implicitly thread safe.
|
|
|
51 SINGLE : Must only be used in single thread mode.
|
|
|
52 MUTEX : Protected by single global mutex objc_runtime_mutex.
|
|
|
53 UNUSED : Not used in the runtime.
|
|
|
54
|
|
|
55 Variable Name: Usage: Defined: Also used in:
|
|
|
56 =========================== ====== ============ =====================
|
|
|
57 __objc_class_hash MUTEX class.c
|
|
|
58 __objc_class_links_resolved UNUSED class.c runtime.h
|
|
|
59 __objc_class_number MUTEX class.c
|
|
|
60 __objc_dangling_categories UNUSED init.c
|
|
|
61 __objc_module_list MUTEX init.c
|
|
|
62 __objc_selector_array MUTEX selector.c
|
|
|
63 __objc_selector_hash MUTEX selector.c
|
|
|
64 __objc_selector_max_index MUTEX selector.c sendmsg.c runtime.h
|
|
|
65 __objc_selector_names MUTEX selector.c
|
|
|
66 __objc_thread_exit_status SAFE thread.c
|
|
|
67 __objc_uninstalled_dtable MUTEX sendmsg.c selector.c
|
|
|
68 _objc_load_callback SAFE init.c objc-api.h
|
|
|
69 _objc_lookup_class SAFE class.c objc-api.h
|
|
|
70 _objc_object_alloc SINGLE objects.c objc-api.h
|
|
|
71 _objc_object_copy SINGLE objects.c objc-api.h
|
|
|
72 _objc_object_dispose SINGLE objects.c objc-api.h
|
|
|
73 frwd_sel SAFE2 sendmsg.c
|
|
|
74 idxsize MUTEX sarray.c sendmsg.c sarray.h
|
|
|
75 initialize_sel SAFE2 sendmsg.c
|
|
|
76 narrays MUTEX sarray.c sendmsg.c sarray.h
|
|
|
77 nbuckets MUTEX sarray.c sendmsg.c sarray.h
|
|
|
78 nindices MUTEX sarray.c sarray.h
|
|
|
79 previous_constructors SAFE1 init.c
|
|
|
80 proto_class SAFE1 init.c
|
|
|
81 unclaimed_categories MUTEX init.c
|
|
|
82 unclaimed_proto_list MUTEX init.c
|
|
|
83 uninitialized_statics MUTEX init.c
|
|
|
84
|
|
|
85 Notes:
|
|
|
86 1) Initialized once in unithread mode.
|
|
|
87 2) Initialized value will always be same, guaranteed by lock on selector
|
|
|
88 hash table.
|
|
|
89
|
|
|
90
|
|
|
91 ******************************************************************************
|
|
|
92 * Frontend/Backend design:
|
|
|
93
|
|
|
94 The design of the Objective-C runtime thread and mutex functions utilizes a
|
|
|
95 frontend/backend implementation.
|
|
|
96
|
|
|
97 The frontend, as characterized by the files thr.h and thr.c, is a set
|
|
|
98 of platform independent structures and functions which represent the
|
|
|
99 user interface. For example, objc_mutex_lock(). Objective-C programs
|
|
|
100 should use these structures and functions for their thread and mutex
|
|
|
101 work if they wish to maintain a high degree of portability across
|
|
|
102 platforms.
|
|
|
103
|
|
|
104 The backend is currently GCC's gthread code (gthr.h and related). For
|
|
|
105 example, __gthread_objc_mutex_lock(). The thread system is
|
|
|
106 automatically configured when GCC is configured. On most platforms
|
|
|
107 this thread backend is able to automatically switch to non-multi-threaded
|
|
|
108 mode if the threading library is not linked in.
|
|
|
109
|
|
|
110 If you want to compile libobjc standalone, then you would need to modify
|
|
|
111 the configure.ac and makefiles for it and you need to import the
|
|
|
112 gthread code from GCC.
|
|
|
113
|
|
|
114 ******************************************************************************
|
|
|
115 * Threads:
|
|
|
116
|
|
|
117 The thread system attempts to create multiple threads using whatever
|
|
|
118 operating system or library thread support is available. It does
|
|
|
119 assume that all system functions are thread safe. Notably this means
|
|
|
120 that the system implementation of malloc and free must be thread safe.
|
|
|
121 If a system has multiple processors, the threads are configured for
|
|
|
122 full parallel processing.
|
|
|
123
|
|
|
124 * Backend initialization functions
|
|
|
125
|
|
|
126 __objc_init_thread_system(void), int
|
|
|
127 Initialize the thread subsystem. Called once by __objc_exec_class.
|
|
|
128 Return -1 if error otherwise return 0.
|
|
|
129
|
|
|
130 __objc_close_thread_system(void), int
|
|
|
131 Closes the thread subsystem, not currently guaranteed to be called.
|
|
|
132 Return -1 if error otherwise return 0.
|
|
|
133
|
|
|
134 *****
|
|
|
135 * Frontend thread functions
|
|
|
136 * User programs should use these functions.
|
|
|
137
|
|
|
138 objc_thread_detach(SEL selector, id object, id argument), objc_thread_t
|
|
|
139 Creates and detaches a new thread. The new thread starts by
|
|
|
140 sending the given selector with a single argument to the
|
|
|
141 given object.
|
|
|
142
|
|
|
143 objc_thread_set_priority(int priority), int
|
|
|
144 Sets a thread's relative priority within the program. Valid
|
|
|
145 options are:
|
|
|
146
|
|
|
147 OBJC_THREAD_INTERACTIVE_PRIORITY
|
|
|
148 OBJC_THREAD_BACKGROUND_PRIORITY
|
|
|
149 OBJC_THREAD_LOW_PRIORITY
|
|
|
150
|
|
|
151 objc_thread_get_priority(void), int
|
|
|
152 Query a thread's priority.
|
|
|
153
|
|
|
154 objc_thread_yield(void), void
|
|
|
155 Yields processor to another thread with equal or higher
|
|
|
156 priority. It is up to the system scheduler to determine if
|
|
|
157 the processor is taken or not.
|
|
|
158
|
|
|
159 objc_thread_exit(void), int
|
|
|
160 Terminates a thread. If this is the last thread executing
|
|
|
161 then the program will terminate.
|
|
|
162
|
|
|
163 objc_thread_id(void), int
|
|
|
164 Returns the current thread's id.
|
|
|
165
|
|
|
166 objc_thread_set_data(void *value), int
|
|
|
167 Set a pointer to the thread's local storage. Local storage is
|
|
|
168 thread specific.
|
|
|
169
|
|
|
170 objc_thread_get_data(void), void *
|
|
|
171 Returns the pointer to the thread's local storage.
|
|
|
172
|
|
|
173 *****
|
|
|
174 * Backend thread functions
|
|
|
175 * User programs should *NOT* directly call these functions.
|
|
|
176
|
|
|
177 __gthr_objc_thread_detach(void (*func)(void *arg), void *arg), objc_thread_t
|
|
|
178 Spawns a new thread executing func, called by objc_thread_detach.
|
|
|
179 Return NULL if error otherwise return thread id.
|
|
|
180
|
|
|
181 __gthr_objc_thread_set_priority(int priority), int
|
|
|
182 Set the thread's priority, called by objc_thread_set_priority.
|
|
|
183 Return -1 if error otherwise return 0.
|
|
|
184
|
|
|
185 __gthr_objc_thread_get_priority(void), int
|
|
|
186 Query a thread's priority, called by objc_thread_get_priority.
|
|
|
187 Return -1 if error otherwise return the priority.
|
|
|
188
|
|
|
189 __gthr_objc_thread_yield(void), void
|
|
|
190 Yields the processor, called by objc_thread_yield.
|
|
|
191
|
|
|
192 __gthr_objc_thread_exit(void), int
|
|
|
193 Terminates the thread, called by objc_thread_exit.
|
|
|
194 Return -1 if error otherwise function does not return.
|
|
|
195
|
|
|
196 __gthr_objc_thread_id(void), objc_thread_t
|
|
|
197 Returns the current thread's id, called by objc_thread_id.
|
|
|
198 Return -1 if error otherwise return thread id.
|
|
|
199
|
|
|
200 __gthr_objc_thread_set_data(void *value), int
|
|
|
201 Set pointer for thread local storage, called by objc_thread_set_data.
|
|
|
202 Returns -1 if error otherwise return 0.
|
|
|
203
|
|
|
204 __gthr_objc_thread_get_data(void), void *
|
|
|
205 Returns the pointer to the thread's local storage.
|
|
|
206 Returns NULL if error, called by objc_thread_get_data.
|
|
|
207
|
|
|
208
|
|
|
209 ******************************************************************************
|
|
|
210 * Mutexes:
|
|
|
211
|
|
|
212 Mutexes can be locked recursively. Each locked mutex remembers
|
|
|
213 its owner (by thread id) and how many times it has been locked. The
|
|
|
214 last unlock on a mutex removes the system lock and allows other
|
|
|
215 threads to access the mutex.
|
|
|
216
|
|
|
217 *****
|
|
|
218 * Frontend mutex functions
|
|
|
219 * User programs should use these functions.
|
|
|
220
|
|
|
221 objc_mutex_allocate(void), objc_mutex_t
|
|
|
222 Allocates a new mutex. Mutex is initially unlocked.
|
|
|
223 Return NULL if error otherwise return mutex pointer.
|
|
|
224
|
|
|
225 objc_mutex_deallocate(objc_mutex_t mutex), int
|
|
|
226 Free a mutex. Before freeing the mutex, makes sure that no
|
|
|
227 one else is using it.
|
|
|
228 Return -1 if error otherwise return 0.
|
|
|
229
|
|
|
230 objc_mutex_lock(objc_mutex_t mutex), int
|
|
|
231 Locks a mutex. As mentioned earlier, the same thread may call
|
|
|
232 this routine repeatedly.
|
|
|
233 Return -1 if error otherwise return 0.
|
|
|
234
|
|
|
235 objc_mutex_trylock(objc_mutex_t mutex), int
|
|
|
236 Attempts to lock a mutex. If lock on mutex can be acquired
|
|
|
237 then function operates exactly as objc_mutex_lock.
|
|
|
238 Return -1 if failed to acquire lock otherwise return 0.
|
|
|
239
|
|
|
240 objc_mutex_unlock(objc_mutex_t mutex), int
|
|
|
241 Unlocks the mutex by one level. Other threads may not acquire
|
|
|
242 the mutex until this thread has released all locks on it.
|
|
|
243 Return -1 if error otherwise return 0.
|
|
|
244
|
|
|
245 *****
|
|
|
246 * Backend mutex functions
|
|
|
247 * User programs should *NOT* directly call these functions.
|
|
|
248
|
|
|
249 __gthr_objc_mutex_allocate(objc_mutex_t mutex), int
|
|
|
250 Allocates a new mutex, called by objc_mutex_allocate.
|
|
|
251 Return -1 if error otherwise return 0.
|
|
|
252
|
|
|
253 __gthr_objc_mutex_deallocate(objc_mutex_t mutex), int
|
|
|
254 Free a mutex, called by objc_mutex_deallocate.
|
|
|
255 Return -1 if error otherwise return 0.
|
|
|
256
|
|
|
257 __gthr_objc_mutex_lock(objc_mutex_t mutex), int
|
|
|
258 Locks a mutex, called by objc_mutex_lock.
|
|
|
259 Return -1 if error otherwise return 0.
|
|
|
260
|
|
|
261 __gthr_objc_mutex_trylock(objc_mutex_t mutex), int
|
|
|
262 Attempts to lock a mutex, called by objc_mutex_trylock.
|
|
|
263 Return -1 if failed to acquire lock or error otherwise return 0.
|
|
|
264
|
|
|
265 __gthr_objc_mutex_unlock(objc_mutex_t mutex), int
|
|
|
266 Unlocks the mutex, called by objc_mutex_unlock.
|
|
|
267 Return -1 if error otherwise return 0.
|
|
|
268
|
|
|
269 ******************************************************************************
|
|
|
270 * Condition Mutexes:
|
|
|
271
|
|
|
272 Mutexes can be locked recursively. Each locked mutex remembers
|
|
|
273 its owner (by thread id) and how many times it has been locked. The
|
|
|
274 last unlock on a mutex removes the system lock and allows other
|
|
|
275 threads to access the mutex.
|
|
|
276
|
|
|
277 *
|
|
|
278 * Frontend condition mutex functions
|
|
|
279 * User programs should use these functions.
|
|
|
280 *
|
|
|
281
|
|
|
282 objc_condition_allocate(void), objc_condition_t
|
|
|
283 Allocate a condition mutex.
|
|
|
284 Return NULL if error otherwise return condition pointer.
|
|
|
285
|
|
|
286 objc_condition_deallocate(objc_condition_t condition), int
|
|
|
287 Deallocate a condition. Note that this includes an implicit
|
|
|
288 condition_broadcast to insure that waiting threads have the
|
|
|
289 opportunity to wake. It is legal to dealloc a condition only
|
|
|
290 if no other thread is/will be using it. Does NOT check for
|
|
|
291 other threads waiting but just wakes them up.
|
|
|
292 Return -1 if error otherwise return 0.
|
|
|
293
|
|
|
294 objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int
|
|
|
295 Wait on the condition unlocking the mutex until objc_condition_signal()
|
|
|
296 or objc_condition_broadcast() are called for the same condition. The
|
|
|
297 given mutex *must* have the depth 1 so that it can be unlocked
|
|
|
298 here, for someone else can lock it and signal/broadcast the condition.
|
|
|
299 The mutex is used to lock access to the shared data that make up the
|
|
|
300 "condition" predicate.
|
|
|
301 Return -1 if error otherwise return 0.
|
|
|
302
|
|
|
303 objc_condition_broadcast(objc_condition_t condition), int
|
|
|
304 Wake up all threads waiting on this condition. It is recommended that
|
|
|
305 the called would lock the same mutex as the threads in
|
|
|
306 objc_condition_wait before changing the "condition predicate"
|
|
|
307 and make this call and unlock it right away after this call.
|
|
|
308 Return -1 if error otherwise return 0.
|
|
|
309
|
|
|
310 objc_condition_signal(objc_condition_t condition), int
|
|
|
311 Wake up one thread waiting on this condition.
|
|
|
312 Return -1 if error otherwise return 0.
|
|
|
313
|
|
|
314 *
|
|
|
315 * Backend condition mutex functions
|
|
|
316 * User programs should *NOT* directly call these functions.
|
|
|
317 *
|
|
|
318
|
|
|
319 __gthr_objc_condition_allocate(objc_condition_t condition), int
|
|
|
320 Allocate a condition mutex, called by objc_condition_allocate.
|
|
|
321 Return -1 if error otherwise return 0.
|
|
|
322
|
|
|
323 __gthr_objc_condition_deallocate(objc_condition_t condition), int
|
|
|
324 Deallocate a condition, called by objc_condition_deallocate.
|
|
|
325 Return -1 if error otherwise return 0.
|
|
|
326
|
|
|
327 __gthr_objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int
|
|
|
328 Wait on the condition, called by objc_condition_wait.
|
|
|
329 Return -1 if error otherwise return 0 when condition is met.
|
|
|
330
|
|
|
331 __gthr_objc_condition_broadcast(objc_condition_t condition), int
|
|
|
332 Wake up all threads waiting on this condition.
|
|
|
333 Called by objc_condition_broadcast.
|
|
|
334 Return -1 if error otherwise return 0.
|
|
|
335
|
|
|
336 __gthr_objc_condition_signal(objc_condition_t condition), int
|
|
|
337 Wake up one thread waiting on this condition.
|
|
|
338 Called by objc_condition_signal.
|
|
|
339 Return -1 if error otherwise return 0.
|
