]>
Commit | Line | Data |
---|---|---|
005dda25 BE |
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. Objective-C programs should use these structures and | |
100 | functions for their thread and mutex work if they wish to maintain a | |
101 | high degree of portability across platforms. | |
102 | ||
103 | The backend is composed of a file with the necessary code to map the ObjC | |
104 | thread and mutex to a platform specific implementation. For example, the | |
27132e64 NP |
105 | file thr-solaris.c contains the implementation for Solaris. |
106 | ||
107 | If you are compiling libobjc as part of GCC, the thr-objc.c backend is | |
108 | always used; this backend uses GCC's gthread code. The thread system | |
109 | is automatically configured when GCC is configured. Important: make | |
110 | sure you configure GCC using `--enable-threads' if you want threads ! | |
111 | ||
112 | If you want to compile libobjc standalone, then you would need to | |
113 | modify the configure.in and makefiles for it; and you need to pick an | |
114 | appropriate backend file for the target platform; you make this choice | |
115 | by assigning the OBJC_THREAD_FILE make variable to the basename of the | |
116 | backend file. For example, OBJC_THREAD_FILE=thr-posix would indicate | |
117 | that the generic posix backend file, thr-posix.c, should be compiled | |
118 | with the ObjC runtime library. If your platform does not support | |
119 | threads then you should specify the OBJC_THREAD_FILE=thr-single | |
120 | backend file to compile the ObjC runtime library without thread or | |
121 | mutex support; note that programs which rely upon the ObjC thread and | |
122 | mutex functions will compile and link correctly but attempting to | |
123 | create a thread or mutex will result in an error. | |
124 | ||
005dda25 BE |
125 | It is questionable whether it is really necessary to have both a |
126 | frontend and backend function for all available functionality. On the | |
127 | one hand, it provides a clear, consistent differentiation between what | |
128 | is public and what is private with the downside of having the overhead | |
27132e64 NP |
129 | of multiple functions calls. For example, the function to have a |
130 | thread yield the processor is objc_thread_yield; in the current | |
131 | implementation this produces a function call set: | |
005dda25 BE |
132 | |
133 | objc_thread_yield() -> __objc_thread_yield() -> system yield function | |
134 | ||
135 | This has two extra function calls over calling the platform specific function | |
136 | explicitly, but the issue is whether only the overhead of a single function | |
137 | is necessary. | |
138 | ||
139 | objc_thread_yield() -> system yield function | |
140 | ||
141 | This breaks the public/private dichotomy between the frontend/backend | |
142 | for the sake of efficiency. It is possible to just use a preprocessor | |
143 | define so as to eliminate the extra function call: | |
144 | ||
145 | #define objc_thread_yield() __objc_thread_yield() | |
146 | ||
147 | This has the undesirable effect that if objc_thread_yield is actually | |
148 | turned into a function based upon future need; then ObjC programs which | |
149 | access the thread functions would need to be recompiled versus just | |
150 | being relinked. | |
151 | ||
152 | ****************************************************************************** | |
153 | * Threads: | |
154 | ||
155 | The thread system attempts to create multiple threads using whatever | |
156 | operating system or library thread support is available. It does | |
157 | assume that all system functions are thread safe. Notably this means | |
158 | that the system implementation of malloc and free must be thread safe. | |
159 | If a system has multiple processors, the threads are configured for | |
160 | full parallel processing. | |
161 | ||
162 | * Backend initialization functions | |
163 | ||
164 | __objc_init_thread_system(void), int | |
165 | Initialize the thread subsystem. Called once by __objc_exec_class. | |
166 | Return -1 if error otherwise return 0. | |
167 | ||
168 | __objc_close_thread_system(void), int | |
169 | Closes the thread subsystem, not currently guaranteed to be called. | |
170 | Return -1 if error otherwise return 0. | |
171 | ||
172 | ***** | |
173 | * Frontend thread functions | |
174 | * User programs should use these functions. | |
175 | ||
176 | objc_thread_detach(SEL selector, id object, id argument), objc_thread_t | |
177 | Creates and detaches a new thread. The new thread starts by | |
178 | sending the given selector with a single argument to the | |
179 | given object. | |
180 | ||
181 | objc_thread_set_priority(int priority), int | |
182 | Sets a thread's relative priority within the program. Valid | |
183 | options are: | |
184 | ||
185 | OBJC_THREAD_INTERACTIVE_PRIORITY | |
186 | OBJC_THREAD_BACKGROUND_PRIORITY | |
187 | OBJC_THREAD_LOW_PRIORITY | |
188 | ||
189 | objc_thread_get_priority(void), int | |
190 | Query a thread's priority. | |
191 | ||
192 | objc_thread_yield(void), void | |
193 | Yields processor to another thread with equal or higher | |
194 | priority. It is up to the system scheduler to determine if | |
195 | the processor is taken or not. | |
196 | ||
197 | objc_thread_exit(void), int | |
198 | Terminates a thread. If this is the last thread executing | |
199 | then the program will terminate. | |
200 | ||
201 | objc_thread_id(void), int | |
202 | Returns the current thread's id. | |
203 | ||
204 | objc_thread_set_data(void *value), int | |
205 | Set a pointer to the thread's local storage. Local storage is | |
206 | thread specific. | |
207 | ||
208 | objc_thread_get_data(void), void * | |
209 | Returns the pointer to the thread's local storage. | |
210 | ||
211 | ***** | |
212 | * Backend thread functions | |
213 | * User programs should *NOT* directly call these functions. | |
214 | ||
215 | __objc_thread_detach(void (*func)(void *arg), void *arg), objc_thread_t | |
216 | Spawns a new thread executing func, called by objc_thread_detach. | |
217 | Return NULL if error otherwise return thread id. | |
218 | ||
219 | __objc_thread_set_priority(int priority), int | |
220 | Set the thread's priority, called by objc_thread_set_priority. | |
221 | Return -1 if error otherwise return 0. | |
222 | ||
223 | __objc_thread_get_priority(void), int | |
224 | Query a thread's priority, called by objc_thread_get_priority. | |
225 | Return -1 if error otherwise return the priority. | |
226 | ||
227 | __objc_thread_yield(void), void | |
228 | Yields the processor, called by objc_thread_yield. | |
229 | ||
230 | __objc_thread_exit(void), int | |
231 | Terminates the thread, called by objc_thread_exit. | |
232 | Return -1 if error otherwise function does not return. | |
233 | ||
234 | __objc_thread_id(void), objc_thread_t | |
235 | Returns the current thread's id, called by objc_thread_id. | |
236 | Return -1 if error otherwise return thread id. | |
237 | ||
238 | __objc_thread_set_data(void *value), int | |
239 | Set pointer for thread local storage, called by objc_thread_set_data. | |
240 | Returns -1 if error otherwise return 0. | |
241 | ||
242 | __objc_thread_get_data(void), void * | |
243 | Returns the pointer to the thread's local storage. | |
244 | Returns NULL if error, called by objc_thread_get_data. | |
245 | ||
246 | ||
247 | ****************************************************************************** | |
248 | * Mutexes: | |
249 | ||
250 | Mutexes can be locked recursively. Each locked mutex remembers | |
251 | its owner (by thread id) and how many times it has been locked. The | |
252 | last unlock on a mutex removes the system lock and allows other | |
253 | threads to access the mutex. | |
254 | ||
255 | ***** | |
256 | * Frontend mutex functions | |
257 | * User programs should use these functions. | |
258 | ||
259 | objc_mutex_allocate(void), objc_mutex_t | |
260 | Allocates a new mutex. Mutex is initially unlocked. | |
261 | Return NULL if error otherwise return mutex pointer. | |
262 | ||
263 | objc_mutex_deallocate(objc_mutex_t mutex), int | |
264 | Free a mutex. Before freeing the mutex, makes sure that no | |
265 | one else is using it. | |
266 | Return -1 if error otherwise return 0. | |
267 | ||
268 | objc_mutex_lock(objc_mutex_t mutex), int | |
269 | Locks a mutex. As mentioned earlier, the same thread may call | |
270 | this routine repeatedly. | |
271 | Return -1 if error otherwise return 0. | |
272 | ||
273 | objc_mutex_trylock(objc_mutex_t mutex), int | |
274 | Attempts to lock a mutex. If lock on mutex can be acquired | |
275 | then function operates exactly as objc_mutex_lock. | |
276 | Return -1 if failed to acquire lock otherwise return 0. | |
277 | ||
278 | objc_mutex_unlock(objc_mutex_t mutex), int | |
279 | Unlocks the mutex by one level. Other threads may not acquire | |
280 | the mutex until this thread has released all locks on it. | |
281 | Return -1 if error otherwise return 0. | |
282 | ||
283 | ***** | |
284 | * Backend mutex functions | |
285 | * User programs should *NOT* directly call these functions. | |
286 | ||
287 | __objc_mutex_allocate(objc_mutex_t mutex), int | |
288 | Allocates a new mutex, called by objc_mutex_allocate. | |
289 | Return -1 if error otherwise return 0. | |
290 | ||
291 | __objc_mutex_deallocate(objc_mutex_t mutex), int | |
292 | Free a mutex, called by objc_mutex_deallocate. | |
293 | Return -1 if error otherwise return 0. | |
294 | ||
295 | __objc_mutex_lock(objc_mutex_t mutex), int | |
296 | Locks a mutex, called by objc_mutex_lock. | |
297 | Return -1 if error otherwise return 0. | |
298 | ||
299 | __objc_mutex_trylock(objc_mutex_t mutex), int | |
300 | Attempts to lock a mutex, called by objc_mutex_trylock. | |
301 | Return -1 if failed to acquire lock or error otherwise return 0. | |
302 | ||
303 | __objc_mutex_unlock(objc_mutex_t mutex), int | |
304 | Unlocks the mutex, called by objc_mutex_unlock. | |
305 | Return -1 if error otherwise return 0. | |
306 | ||
307 | ****************************************************************************** | |
308 | * Condition Mutexes: | |
309 | ||
310 | Mutexes can be locked recursively. Each locked mutex remembers | |
311 | its owner (by thread id) and how many times it has been locked. The | |
312 | last unlock on a mutex removes the system lock and allows other | |
313 | threads to access the mutex. | |
314 | ||
315 | * | |
316 | * Frontend condition mutex functions | |
317 | * User programs should use these functions. | |
318 | * | |
319 | ||
320 | objc_condition_allocate(void), objc_condition_t | |
321 | Allocate a condition mutex. | |
322 | Return NULL if error otherwise return condition pointer. | |
323 | ||
324 | objc_condition_deallocate(objc_condition_t condition), int | |
325 | Deallocate a condition. Note that this includes an implicit | |
326 | condition_broadcast to insure that waiting threads have the | |
327 | opportunity to wake. It is legal to dealloc a condition only | |
328 | if no other thread is/will be using it. Does NOT check for | |
329 | other threads waiting but just wakes them up. | |
330 | Return -1 if error otherwise return 0. | |
331 | ||
332 | objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int | |
333 | Wait on the condition unlocking the mutex until objc_condition_signal() | |
334 | or objc_condition_broadcast() are called for the same condition. The | |
335 | given mutex *must* have the depth 1 so that it can be unlocked | |
336 | here, for someone else can lock it and signal/broadcast the condition. | |
337 | The mutex is used to lock access to the shared data that make up the | |
338 | "condition" predicate. | |
339 | Return -1 if error otherwise return 0. | |
340 | ||
341 | objc_condition_broadcast(objc_condition_t condition), int | |
342 | Wake up all threads waiting on this condition. It is recommended that | |
343 | the called would lock the same mutex as the threads in | |
344 | objc_condition_wait before changing the "condition predicate" | |
345 | and make this call and unlock it right away after this call. | |
346 | Return -1 if error otherwise return 0. | |
347 | ||
348 | objc_condition_signal(objc_condition_t condition), int | |
349 | Wake up one thread waiting on this condition. | |
350 | Return -1 if error otherwise return 0. | |
351 | ||
352 | * | |
353 | * Backend condition mutex functions | |
354 | * User programs should *NOT* directly call these functions. | |
355 | * | |
356 | ||
357 | __objc_condition_allocate(objc_condition_t condition), int | |
358 | Allocate a condition mutex, called by objc_condition_allocate. | |
359 | Return -1 if error otherwise return 0. | |
360 | ||
361 | __objc_condition_deallocate(objc_condition_t condition), int | |
362 | Deallocate a condition, called by objc_condition_deallocate. | |
363 | Return -1 if error otherwise return 0. | |
364 | ||
365 | __objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int | |
366 | Wait on the condition, called by objc_condition_wait. | |
367 | Return -1 if error otherwise return 0 when condition is met. | |
368 | ||
369 | __objc_condition_broadcast(objc_condition_t condition), int | |
370 | Wake up all threads waiting on this condition. | |
371 | Called by objc_condition_broadcast. | |
372 | Return -1 if error otherwise return 0. | |
373 | ||
374 | __objc_condition_signal(objc_condition_t condition), int | |
375 | Wake up one thread waiting on this condition. | |
376 | Called by objc_condition_signal. | |
377 | Return -1 if error otherwise return 0. |