1 /* GNU Objective C Runtime Thread Interface
2 Copyright (C) 1996-2023 Free Software Foundation, Inc.
3 Contributed by Galen C. Hunt (gchunt@cs.rochester.edu)
4
5 This file is part of GCC.
6
7 GCC is free software; you can redistribute it and/or modify it under the
8 terms of the GNU General Public License as published by the Free Software
9 Foundation; either version 3, or (at your option) any later version.
10
11 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
12 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
14 details.
15
16 Under Section 7 of GPL version 3, you are granted additional
17 permissions described in the GCC Runtime Library Exception, version
18 3.1, as published by the Free Software Foundation.
19
20 You should have received a copy of the GNU General Public License and
21 a copy of the GCC Runtime Library Exception along with this program;
22 see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 <http://www.gnu.org/licenses/>. */
24
25 #include "objc-private/common.h"
26 #include "objc-private/error.h"
27 #define _LIBOBJC
28 #include "config.h"
29 #include "tconfig.h"
30 #include "coretypes.h"
31 #include "tm.h"
32 #include "defaults.h"
33 #include "objc/thr.h"
34 #include "objc/message.h" /* For objc_msg_lookup(). */
35 #include "objc/runtime.h"
36 #include "objc-private/module-abi-8.h"
37 #include "objc-private/runtime.h"
38 #include <gthr.h>
39
40 #include <stdlib.h>
41
42 /* Global exit status. */
43 int __objc_thread_exit_status = 0;
44
45 /* Flag which lets us know if we ever became multi threaded. */
46 int __objc_is_multi_threaded = 0;
47
48 /* The hook function called when the runtime becomes multi
49 threaded. */
50 objc_thread_callback _objc_became_multi_threaded = NULL;
51
52 /* Use this to set the hook function that will be called when the
53 runtime initially becomes multi threaded. The hook function is
54 only called once, meaning only when the 2nd thread is spawned, not
55 for each and every thread.
56
57 It returns the previous hook function or NULL if there is none.
58
59 A program outside of the runtime could set this to some function so
60 it can be informed; for example, the GNUstep Base Library sets it
61 so it can implement the NSBecomingMultiThreaded notification. */
62 objc_thread_callback objc_set_thread_callback (objc_thread_callback func)
63 {
64 objc_thread_callback temp = _objc_became_multi_threaded;
65 _objc_became_multi_threaded = func;
66 return temp;
67 }
68
69 /* Private functions.
70
71 These functions are utilized by the runtime, but they are not
72 considered part of the public interface. */
73
74 /* Initialize the threads subsystem. */
75 int
76 __objc_init_thread_system(void)
77 {
78 return __gthread_objc_init_thread_system ();
79 }
80
81 /* First function called in a thread, starts everything else.
82
83 This function is passed to the backend by objc_thread_detach as the
84 starting function for a new thread. */
85 struct __objc_thread_start_state
86 {
87 SEL selector;
88 id object;
89 id argument;
90 };
91
92 static void __attribute__((noreturn))
93 __objc_thread_detach_function (struct __objc_thread_start_state *istate)
94 {
95 /* Valid state? */
96 if (istate)
97 {
98 id (*imp) (id, SEL, id);
99 SEL selector = istate->selector;
100 id object = istate->object;
101 id argument = istate->argument;
102
103 /* Don't need anymore so free it. */
104 objc_free (istate);
105
106 /* Clear out the thread local storage. */
107 objc_thread_set_data (NULL);
108
109 /* Check to see if we just became multi threaded. */
110 if (! __objc_is_multi_threaded)
111 {
112 __objc_is_multi_threaded = 1;
113
114 /* Call the hook function. */
115 if (_objc_became_multi_threaded != NULL)
116 (*_objc_became_multi_threaded) ();
117 }
118
119 /* Call the method. */
120 if ((imp = (id (*) (id, SEL, id))objc_msg_lookup (object, selector)))
121 (*imp) (object, selector, argument);
122 else
123 {
124 /* FIXME: Should we abort here ? */
125 _objc_abort ("objc_thread_detach called with bad selector.\n");
126 }
127 }
128 else
129 {
130 /* FIXME: Should we abort here ? */
131 _objc_abort ("objc_thread_detach called with NULL state.\n");
132 }
133
134 /* Exit the thread. */
135 objc_thread_exit ();
136
137 /* Make sure compiler detects no return. */
138 __builtin_trap ();
139 }
140
141 /* Public functions.
142
143 These functions constitute the public interface to the Objective-C
144 thread and mutex functionality. */
145
146 /* Detach a new thread of execution and return its id. Returns NULL
147 if fails. Thread is started by sending message with selector to
148 object. Message takes a single argument. */
149 objc_thread_t
150 objc_thread_detach (SEL selector, id object, id argument)
151 {
152 struct __objc_thread_start_state *istate;
153 objc_thread_t thread_id = NULL;
154
155 /* Allocate the state structure. */
156 if (!(istate = (struct __objc_thread_start_state *)objc_malloc
157 (sizeof (*istate))))
158 return NULL;
159
160 /* Initialize the state structure. */
161 istate->selector = selector;
162 istate->object = object;
163 istate->argument = argument;
164
165 /* Lock access. */
166 objc_mutex_lock (__objc_runtime_mutex);
167
168 /* Call the backend to spawn the thread. */
169 if ((thread_id = __gthread_objc_thread_detach ((void *)__objc_thread_detach_function,
170 istate)) == NULL)
171 {
172 /* Failed! */
173 objc_mutex_unlock (__objc_runtime_mutex);
174 objc_free (istate);
175 return NULL;
176 }
177
178 /* Increment our thread counter. */
179 __objc_runtime_threads_alive++;
180 objc_mutex_unlock (__objc_runtime_mutex);
181
182 return thread_id;
183 }
184
185 /* Set the current thread's priority. */
186 int
187 objc_thread_set_priority (int priority)
188 {
189 return __gthread_objc_thread_set_priority (priority);
190 }
191
192 /* Return the current thread's priority. */
193 int
194 objc_thread_get_priority (void)
195 {
196 return __gthread_objc_thread_get_priority ();
197 }
198
199 /* Yield our process time to another thread. Any BUSY waiting that is
200 done by a thread should use this function to make sure that other
201 threads can make progress even on a lazy uniprocessor system. */
202 void
203 objc_thread_yield (void)
204 {
205 __gthread_objc_thread_yield ();
206 }
207
208 /* Terminate the current tread. Doesn't return. Actually, if it
209 failed returns -1. */
210 int
211 objc_thread_exit (void)
212 {
213 /* Decrement our counter of the number of threads alive. */
214 objc_mutex_lock (__objc_runtime_mutex);
215 __objc_runtime_threads_alive--;
216 objc_mutex_unlock (__objc_runtime_mutex);
217
218 /* Call the backend to terminate the thread. */
219 return __gthread_objc_thread_exit ();
220 }
221
222 /* Returns an integer value which uniquely describes a thread. Must
223 not be NULL which is reserved as a marker for "no thread". */
224 objc_thread_t
225 objc_thread_id (void)
226 {
227 return __gthread_objc_thread_id ();
228 }
229
230 /* Sets the thread's local storage pointer. Returns 0 if successful
231 or -1 if failed. */
232 int
233 objc_thread_set_data (void *value)
234 {
235 return __gthread_objc_thread_set_data (value);
236 }
237
238 /* Returns the thread's local storage pointer. Returns NULL on
239 failure. */
240 void *
241 objc_thread_get_data (void)
242 {
243 return __gthread_objc_thread_get_data ();
244 }
245
246 /* Public mutex functions */
247
248 /* Allocate a mutex. Return the mutex pointer if successful or NULL
249 if the allocation failed for any reason. */
250 objc_mutex_t
251 objc_mutex_allocate (void)
252 {
253 objc_mutex_t mutex;
254
255 /* Allocate the mutex structure. */
256 if (! (mutex = (objc_mutex_t)objc_malloc (sizeof (struct objc_mutex))))
257 return NULL;
258
259 /* Call backend to create the mutex. */
260 if (__gthread_objc_mutex_allocate (mutex))
261 {
262 /* Failed! */
263 objc_free (mutex);
264 return NULL;
265 }
266
267 /* Initialize mutex. */
268 mutex->owner = NULL;
269 mutex->depth = 0;
270 return mutex;
271 }
272
273 /* Deallocate a mutex. Note that this includes an implicit mutex_lock
274 to insure that no one else is using the lock. It is legal to
275 deallocate a lock if we have a lock on it, but illegal to
276 deallocate a lock held by anyone else. Returns the number of locks
277 on the thread. (1 for deallocate). */
278 int
279 objc_mutex_deallocate (objc_mutex_t mutex)
280 {
281 int depth;
282
283 /* Valid mutex? */
284 if (! mutex)
285 return -1;
286
287 /* Acquire lock on mutex. */
288 depth = objc_mutex_lock (mutex);
289
290 /* Call backend to destroy mutex. */
291 if (__gthread_objc_mutex_deallocate (mutex))
292 return -1;
293
294 /* Free the mutex structure. */
295 objc_free (mutex);
296
297 /* Return last depth. */
298 return depth;
299 }
300
301 /* Grab a lock on a mutex. If this thread already has a lock on this
302 mutex then we increment the lock count. If another thread has a
303 lock on the mutex we block and wait for the thread to release the
304 lock. Returns the lock count on the mutex held by this thread. */
305 int
306 objc_mutex_lock (objc_mutex_t mutex)
307 {
308 objc_thread_t thread_id;
309 int status;
310
311 /* Valid mutex? */
312 if (! mutex)
313 return -1;
314
315 /* If we already own the lock then increment depth. */
316 thread_id = __gthread_objc_thread_id ();
317 if (mutex->owner == thread_id)
318 return ++mutex->depth;
319
320 /* Call the backend to lock the mutex. */
321 status = __gthread_objc_mutex_lock (mutex);
322
323 /* Failed? */
324 if (status)
325 return status;
326
327 /* Successfully locked the thread. */
328 mutex->owner = thread_id;
329 return mutex->depth = 1;
330 }
331
332 /* Try to grab a lock on a mutex. If this thread already has a lock
333 on this mutex then we increment the lock count and return it. If
334 another thread has a lock on the mutex returns -1. */
335 int
336 objc_mutex_trylock (objc_mutex_t mutex)
337 {
338 objc_thread_t thread_id;
339 int status;
340
341 /* Valid mutex? */
342 if (! mutex)
343 return -1;
344
345 /* If we already own the lock then increment depth. */
346 thread_id = __gthread_objc_thread_id ();
347 if (mutex->owner == thread_id)
348 return ++mutex->depth;
349
350 /* Call the backend to try to lock the mutex. */
351 status = __gthread_objc_mutex_trylock (mutex);
352
353 /* Failed? */
354 if (status)
355 return status;
356
357 /* Successfully locked the thread. */
358 mutex->owner = thread_id;
359 return mutex->depth = 1;
360 }
361
362 /* Unlocks the mutex by one level. Decrements the lock count on this
363 mutex by one. If the lock count reaches zero, release the lock on
364 the mutex. Returns the lock count on the mutex. It is an error to
365 attempt to unlock a mutex which this thread doesn't hold in which
366 case return -1 and the mutex is unaffected. */
367 int
368 objc_mutex_unlock (objc_mutex_t mutex)
369 {
370 objc_thread_t thread_id;
371 int status;
372
373 /* Valid mutex? */
374 if (! mutex)
375 return -1;
376
377 /* If another thread owns the lock then abort. */
378 thread_id = __gthread_objc_thread_id ();
379 if (mutex->owner != thread_id)
380 return -1;
381
382 /* Decrement depth and return. */
383 if (mutex->depth > 1)
384 return --mutex->depth;
385
386 /* Depth down to zero so we are no longer the owner. */
387 mutex->depth = 0;
388 mutex->owner = NULL;
389
390 /* Have the backend unlock the mutex. */
391 status = __gthread_objc_mutex_unlock (mutex);
392
393 /* Failed? */
394 if (status)
395 return status;
396
397 return 0;
398 }
399
400 /* Public condition mutex functions */
401
402 /* Allocate a condition. Return the condition pointer if successful
403 or NULL if the allocation failed for any reason. */
404 objc_condition_t
405 objc_condition_allocate (void)
406 {
407 objc_condition_t condition;
408
409 /* Allocate the condition mutex structure. */
410 if (! (condition =
411 (objc_condition_t) objc_malloc (sizeof (struct objc_condition))))
412 return NULL;
413
414 /* Call the backend to create the condition mutex. */
415 if (__gthread_objc_condition_allocate (condition))
416 {
417 /* Failed! */
418 objc_free (condition);
419 return NULL;
420 }
421
422 /* Success! */
423 return condition;
424 }
425
426 /* Deallocate a condition. Note that this includes an implicit
427 condition_broadcast to insure that waiting threads have the
428 opportunity to wake. It is legal to dealloc a condition only if no
429 other thread is/will be using it. Here we do NOT check for other
430 threads waiting but just wake them up. */
431 int
432 objc_condition_deallocate (objc_condition_t condition)
433 {
434 /* Broadcast the condition. */
435 if (objc_condition_broadcast (condition))
436 return -1;
437
438 /* Call the backend to destroy. */
439 if (__gthread_objc_condition_deallocate (condition))
440 return -1;
441
442 /* Free the condition mutex structure. */
443 objc_free (condition);
444
445 return 0;
446 }
447
448 /* Wait on the condition unlocking the mutex until
449 objc_condition_signal () or objc_condition_broadcast () are called
450 for the same condition. The given mutex *must* have the depth set
451 to 1 so that it can be unlocked here, so that someone else can lock
452 it and signal/broadcast the condition. The mutex is used to lock
453 access to the shared data that make up the "condition"
454 predicate. */
455 int
456 objc_condition_wait (objc_condition_t condition, objc_mutex_t mutex)
457 {
458 objc_thread_t thread_id;
459
460 /* Valid arguments? */
461 if (! mutex || ! condition)
462 return -1;
463
464 /* Make sure we are owner of mutex. */
465 thread_id = __gthread_objc_thread_id ();
466 if (mutex->owner != thread_id)
467 return -1;
468
469 /* Cannot be locked more than once. */
470 if (mutex->depth > 1)
471 return -1;
472
473 /* Virtually unlock the mutex. */
474 mutex->depth = 0;
475 mutex->owner = (objc_thread_t)NULL;
476
477 /* Call the backend to wait. */
478 __gthread_objc_condition_wait (condition, mutex);
479
480 /* Make ourselves owner of the mutex. */
481 mutex->owner = thread_id;
482 mutex->depth = 1;
483
484 return 0;
485 }
486
487 /* Wake up all threads waiting on this condition. It is recommended
488 that the called would lock the same mutex as the threads in
489 objc_condition_wait before changing the "condition predicate" and
490 make this call and unlock it right away after this call. */
491 int
492 objc_condition_broadcast (objc_condition_t condition)
493 {
494 /* Valid condition mutex? */
495 if (! condition)
496 return -1;
497
498 return __gthread_objc_condition_broadcast (condition);
499 }
500
501 /* Wake up one thread waiting on this condition. It is recommended
502 that the called would lock the same mutex as the threads in
503 objc_condition_wait before changing the "condition predicate" and
504 make this call and unlock it right away after this call. */
505 int
506 objc_condition_signal (objc_condition_t condition)
507 {
508 /* Valid condition mutex? */
509 if (! condition)
510 return -1;
511
512 return __gthread_objc_condition_signal (condition);
513 }
514
515 /* Make the objc thread system aware that a thread which is managed
516 (started, stopped) by external code could access objc facilities
517 from now on. This is used when you are interfacing with some
518 external non-objc-based environment/system - you must call
519 objc_thread_add () before an alien thread makes any calls to
520 Objective-C. Do not cause the _objc_became_multi_threaded hook to
521 be executed. */
522 void
523 objc_thread_add (void)
524 {
525 objc_mutex_lock (__objc_runtime_mutex);
526 __objc_is_multi_threaded = 1;
527 __objc_runtime_threads_alive++;
528 objc_mutex_unlock (__objc_runtime_mutex);
529 }
530
531 /* Make the objc thread system aware that a thread managed (started,
532 stopped) by some external code will no longer access objc and thus
533 can be forgotten by the objc thread system. Call
534 objc_thread_remove () when your alien thread is done with making
535 calls to Objective-C. */
536 void
537 objc_thread_remove (void)
538 {
539 objc_mutex_lock (__objc_runtime_mutex);
540 __objc_runtime_threads_alive--;
541 objc_mutex_unlock (__objc_runtime_mutex);
542 }
543