]>
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 | |
88a2722e NP |
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.in and makefiles for it and you need to import the | |
112 | gthread code from GCC. | |
113 | ||
005dda25 BE |
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 | ||
88a2722e | 177 | __gthr_objc_thread_detach(void (*func)(void *arg), void *arg), objc_thread_t |
005dda25 BE |
178 | Spawns a new thread executing func, called by objc_thread_detach. |
179 | Return NULL if error otherwise return thread id. | |
180 | ||
88a2722e | 181 | __gthr_objc_thread_set_priority(int priority), int |
005dda25 BE |
182 | Set the thread's priority, called by objc_thread_set_priority. |
183 | Return -1 if error otherwise return 0. | |
184 | ||
88a2722e | 185 | __gthr_objc_thread_get_priority(void), int |
005dda25 BE |
186 | Query a thread's priority, called by objc_thread_get_priority. |
187 | Return -1 if error otherwise return the priority. | |
188 | ||
88a2722e | 189 | __gthr_objc_thread_yield(void), void |
005dda25 BE |
190 | Yields the processor, called by objc_thread_yield. |
191 | ||
88a2722e | 192 | __gthr_objc_thread_exit(void), int |
005dda25 BE |
193 | Terminates the thread, called by objc_thread_exit. |
194 | Return -1 if error otherwise function does not return. | |
195 | ||
88a2722e | 196 | __gthr_objc_thread_id(void), objc_thread_t |
005dda25 BE |
197 | Returns the current thread's id, called by objc_thread_id. |
198 | Return -1 if error otherwise return thread id. | |
199 | ||
88a2722e | 200 | __gthr_objc_thread_set_data(void *value), int |
005dda25 BE |
201 | Set pointer for thread local storage, called by objc_thread_set_data. |
202 | Returns -1 if error otherwise return 0. | |
203 | ||
88a2722e | 204 | __gthr_objc_thread_get_data(void), void * |
005dda25 BE |
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 | ||
88a2722e | 249 | __gthr_objc_mutex_allocate(objc_mutex_t mutex), int |
005dda25 BE |
250 | Allocates a new mutex, called by objc_mutex_allocate. |
251 | Return -1 if error otherwise return 0. | |
252 | ||
88a2722e | 253 | __gthr_objc_mutex_deallocate(objc_mutex_t mutex), int |
005dda25 BE |
254 | Free a mutex, called by objc_mutex_deallocate. |
255 | Return -1 if error otherwise return 0. | |
256 | ||
88a2722e | 257 | __gthr_objc_mutex_lock(objc_mutex_t mutex), int |
005dda25 BE |
258 | Locks a mutex, called by objc_mutex_lock. |
259 | Return -1 if error otherwise return 0. | |
260 | ||
88a2722e | 261 | __gthr_objc_mutex_trylock(objc_mutex_t mutex), int |
005dda25 BE |
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 | ||
88a2722e | 265 | __gthr_objc_mutex_unlock(objc_mutex_t mutex), int |
005dda25 BE |
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 | ||
88a2722e | 319 | __gthr_objc_condition_allocate(objc_condition_t condition), int |
005dda25 BE |
320 | Allocate a condition mutex, called by objc_condition_allocate. |
321 | Return -1 if error otherwise return 0. | |
322 | ||
88a2722e | 323 | __gthr_objc_condition_deallocate(objc_condition_t condition), int |
005dda25 BE |
324 | Deallocate a condition, called by objc_condition_deallocate. |
325 | Return -1 if error otherwise return 0. | |
326 | ||
88a2722e | 327 | __gthr_objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int |
005dda25 BE |
328 | Wait on the condition, called by objc_condition_wait. |
329 | Return -1 if error otherwise return 0 when condition is met. | |
330 | ||
88a2722e | 331 | __gthr_objc_condition_broadcast(objc_condition_t condition), int |
005dda25 BE |
332 | Wake up all threads waiting on this condition. |
333 | Called by objc_condition_broadcast. | |
334 | Return -1 if error otherwise return 0. | |
335 | ||
88a2722e | 336 | __gthr_objc_condition_signal(objc_condition_t condition), int |
005dda25 BE |
337 | Wake up one thread waiting on this condition. |
338 | Called by objc_condition_signal. | |
339 | Return -1 if error otherwise return 0. |