Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 339 lines (267 sloc) 13.179 kb
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
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
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
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
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
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
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
177 __gthr_objc_thread_detach(void (*func)(void *arg), void *arg), objc_thread_t
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
178 Spawns a new thread executing func, called by objc_thread_detach.
179 Return NULL if error otherwise return thread id.
180
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
181 __gthr_objc_thread_set_priority(int priority), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
182 Set the thread's priority, called by objc_thread_set_priority.
183 Return -1 if error otherwise return 0.
184
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
185 __gthr_objc_thread_get_priority(void), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
186 Query a thread's priority, called by objc_thread_get_priority.
187 Return -1 if error otherwise return the priority.
188
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
189 __gthr_objc_thread_yield(void), void
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
190 Yields the processor, called by objc_thread_yield.
191
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
192 __gthr_objc_thread_exit(void), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
193 Terminates the thread, called by objc_thread_exit.
194 Return -1 if error otherwise function does not return.
195
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
196 __gthr_objc_thread_id(void), objc_thread_t
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
197 Returns the current thread's id, called by objc_thread_id.
198 Return -1 if error otherwise return thread id.
199
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
200 __gthr_objc_thread_set_data(void *value), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
201 Set pointer for thread local storage, called by objc_thread_set_data.
202 Returns -1 if error otherwise return 0.
203
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
204 __gthr_objc_thread_get_data(void), void *
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
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
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
249 __gthr_objc_mutex_allocate(objc_mutex_t mutex), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
250 Allocates a new mutex, called by objc_mutex_allocate.
251 Return -1 if error otherwise return 0.
252
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
253 __gthr_objc_mutex_deallocate(objc_mutex_t mutex), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
254 Free a mutex, called by objc_mutex_deallocate.
255 Return -1 if error otherwise return 0.
256
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
257 __gthr_objc_mutex_lock(objc_mutex_t mutex), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
258 Locks a mutex, called by objc_mutex_lock.
259 Return -1 if error otherwise return 0.
260
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
261 __gthr_objc_mutex_trylock(objc_mutex_t mutex), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
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
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
265 __gthr_objc_mutex_unlock(objc_mutex_t mutex), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
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
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
319 __gthr_objc_condition_allocate(objc_condition_t condition), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
320 Allocate a condition mutex, called by objc_condition_allocate.
321 Return -1 if error otherwise return 0.
322
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
323 __gthr_objc_condition_deallocate(objc_condition_t condition), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
324 Deallocate a condition, called by objc_condition_deallocate.
325 Return -1 if error otherwise return 0.
326
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
327 __gthr_objc_condition_wait(objc_condition_t condition, objc_mutex_t mutex), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
328 Wait on the condition, called by objc_condition_wait.
329 Return -1 if error otherwise return 0 when condition is met.
330
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
331 __gthr_objc_condition_broadcast(objc_condition_t condition), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
332 Wake up all threads waiting on this condition.
333 Called by objc_condition_broadcast.
334 Return -1 if error otherwise return 0.
335
6ceebb84 » nicola
2010-09-08 Removed obsolete intermediate threading layer.
336 __gthr_objc_condition_signal(objc_condition_t condition), int
d41977e4 » bje
1998-09-17 Move documentation files from egcs/gcc/objc.
337 Wake up one thread waiting on this condition.
338 Called by objc_condition_signal.
339 Return -1 if error otherwise return 0.
Something went wrong with that request. Please try again.