Fix typo in latest ChangeLog entry addition.
[official-gcc.git] / libobjc / thr.c
blobe8a8f5e84c31e44934336718e2da450710094866
1 /* GNU Objective C Runtime Thread Interface
2 Copyright (C) 1996, 1997, 2009, 2010, 2012 Free Software Foundation, Inc.
3 Contributed by Galen C. Hunt (gchunt@cs.rochester.edu)
5 This file is part of GCC.
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.
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.
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.
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/>. */
25 #include "objc-private/common.h"
26 #include "objc-private/error.h"
27 #define _LIBOBJC
28 /* The line below is needed for declarations of functions such as
29 pthread_mutexattr_settype, without which gthr-posix.h may fail to
30 compile within libobjc. */
31 #define _XOPEN_SOURCE 500
32 #include "config.h"
33 #include "tconfig.h"
34 #include "coretypes.h"
35 #include "tm.h"
36 #include "defaults.h"
37 #include "objc/thr.h"
38 #include "objc/message.h" /* For objc_msg_lookup(). */
39 #include "objc/runtime.h"
40 #include "objc-private/module-abi-8.h"
41 #include "objc-private/runtime.h"
42 #include <gthr.h>
44 #include <stdlib.h>
46 /* Global exit status. */
47 int __objc_thread_exit_status = 0;
49 /* Flag which lets us know if we ever became multi threaded. */
50 int __objc_is_multi_threaded = 0;
52 /* The hook function called when the runtime becomes multi
53 threaded. */
54 objc_thread_callback _objc_became_multi_threaded = NULL;
56 /* Use this to set the hook function that will be called when the
57 runtime initially becomes multi threaded. The hook function is
58 only called once, meaning only when the 2nd thread is spawned, not
59 for each and every thread.
61 It returns the previous hook function or NULL if there is none.
63 A program outside of the runtime could set this to some function so
64 it can be informed; for example, the GNUstep Base Library sets it
65 so it can implement the NSBecomingMultiThreaded notification. */
66 objc_thread_callback objc_set_thread_callback (objc_thread_callback func)
68 objc_thread_callback temp = _objc_became_multi_threaded;
69 _objc_became_multi_threaded = func;
70 return temp;
73 /* Private functions.
75 These functions are utilized by the runtime, but they are not
76 considered part of the public interface. */
78 /* Initialize the threads subsystem. */
79 int
80 __objc_init_thread_system(void)
82 return __gthread_objc_init_thread_system ();
85 /* First function called in a thread, starts everything else.
87 This function is passed to the backend by objc_thread_detach as the
88 starting function for a new thread. */
89 struct __objc_thread_start_state
91 SEL selector;
92 id object;
93 id argument;
96 static void __attribute__((noreturn))
97 __objc_thread_detach_function (struct __objc_thread_start_state *istate)
99 /* Valid state? */
100 if (istate)
102 id (*imp) (id, SEL, id);
103 SEL selector = istate->selector;
104 id object = istate->object;
105 id argument = istate->argument;
107 /* Don't need anymore so free it. */
108 objc_free (istate);
110 /* Clear out the thread local storage. */
111 objc_thread_set_data (NULL);
113 /* Check to see if we just became multi threaded. */
114 if (! __objc_is_multi_threaded)
116 __objc_is_multi_threaded = 1;
118 /* Call the hook function. */
119 if (_objc_became_multi_threaded != NULL)
120 (*_objc_became_multi_threaded) ();
123 /* Call the method. */
124 if ((imp = (id (*) (id, SEL, id))objc_msg_lookup (object, selector)))
125 (*imp) (object, selector, argument);
126 else
128 /* FIXME: Should we abort here ? */
129 _objc_abort ("objc_thread_detach called with bad selector.\n");
132 else
134 /* FIXME: Should we abort here ? */
135 _objc_abort ("objc_thread_detach called with NULL state.\n");
138 /* Exit the thread. */
139 objc_thread_exit ();
141 /* Make sure compiler detects no return. */
142 __builtin_trap ();
145 /* Public functions.
147 These functions constitute the public interface to the Objective-C
148 thread and mutex functionality. */
150 /* Detach a new thread of execution and return its id. Returns NULL
151 if fails. Thread is started by sending message with selector to
152 object. Message takes a single argument. */
153 objc_thread_t
154 objc_thread_detach (SEL selector, id object, id argument)
156 struct __objc_thread_start_state *istate;
157 objc_thread_t thread_id = NULL;
159 /* Allocate the state structure. */
160 if (!(istate = (struct __objc_thread_start_state *)objc_malloc
161 (sizeof (*istate))))
162 return NULL;
164 /* Initialize the state structure. */
165 istate->selector = selector;
166 istate->object = object;
167 istate->argument = argument;
169 /* Lock access. */
170 objc_mutex_lock (__objc_runtime_mutex);
172 /* Call the backend to spawn the thread. */
173 if ((thread_id = __gthread_objc_thread_detach ((void *)__objc_thread_detach_function,
174 istate)) == NULL)
176 /* Failed! */
177 objc_mutex_unlock (__objc_runtime_mutex);
178 objc_free (istate);
179 return NULL;
182 /* Increment our thread counter. */
183 __objc_runtime_threads_alive++;
184 objc_mutex_unlock (__objc_runtime_mutex);
186 return thread_id;
189 /* Set the current thread's priority. */
191 objc_thread_set_priority (int priority)
193 return __gthread_objc_thread_set_priority (priority);
196 /* Return the current thread's priority. */
198 objc_thread_get_priority (void)
200 return __gthread_objc_thread_get_priority ();
203 /* Yield our process time to another thread. Any BUSY waiting that is
204 done by a thread should use this function to make sure that other
205 threads can make progress even on a lazy uniprocessor system. */
206 void
207 objc_thread_yield (void)
209 __gthread_objc_thread_yield ();
212 /* Terminate the current tread. Doesn't return. Actually, if it
213 failed returns -1. */
215 objc_thread_exit (void)
217 /* Decrement our counter of the number of threads alive. */
218 objc_mutex_lock (__objc_runtime_mutex);
219 __objc_runtime_threads_alive--;
220 objc_mutex_unlock (__objc_runtime_mutex);
222 /* Call the backend to terminate the thread. */
223 return __gthread_objc_thread_exit ();
226 /* Returns an integer value which uniquely describes a thread. Must
227 not be NULL which is reserved as a marker for "no thread". */
228 objc_thread_t
229 objc_thread_id (void)
231 return __gthread_objc_thread_id ();
234 /* Sets the thread's local storage pointer. Returns 0 if successful
235 or -1 if failed. */
237 objc_thread_set_data (void *value)
239 return __gthread_objc_thread_set_data (value);
242 /* Returns the thread's local storage pointer. Returns NULL on
243 failure. */
244 void *
245 objc_thread_get_data (void)
247 return __gthread_objc_thread_get_data ();
250 /* Public mutex functions */
252 /* Allocate a mutex. Return the mutex pointer if successful or NULL
253 if the allocation failed for any reason. */
254 objc_mutex_t
255 objc_mutex_allocate (void)
257 objc_mutex_t mutex;
259 /* Allocate the mutex structure. */
260 if (! (mutex = (objc_mutex_t)objc_malloc (sizeof (struct objc_mutex))))
261 return NULL;
263 /* Call backend to create the mutex. */
264 if (__gthread_objc_mutex_allocate (mutex))
266 /* Failed! */
267 objc_free (mutex);
268 return NULL;
271 /* Initialize mutex. */
272 mutex->owner = NULL;
273 mutex->depth = 0;
274 return mutex;
277 /* Deallocate a mutex. Note that this includes an implicit mutex_lock
278 to insure that no one else is using the lock. It is legal to
279 deallocate a lock if we have a lock on it, but illegal to
280 deallocate a lock held by anyone else. Returns the number of locks
281 on the thread. (1 for deallocate). */
283 objc_mutex_deallocate (objc_mutex_t mutex)
285 int depth;
287 /* Valid mutex? */
288 if (! mutex)
289 return -1;
291 /* Acquire lock on mutex. */
292 depth = objc_mutex_lock (mutex);
294 /* Call backend to destroy mutex. */
295 if (__gthread_objc_mutex_deallocate (mutex))
296 return -1;
298 /* Free the mutex structure. */
299 objc_free (mutex);
301 /* Return last depth. */
302 return depth;
305 /* Grab a lock on a mutex. If this thread already has a lock on this
306 mutex then we increment the lock count. If another thread has a
307 lock on the mutex we block and wait for the thread to release the
308 lock. Returns the lock count on the mutex held by this thread. */
310 objc_mutex_lock (objc_mutex_t mutex)
312 objc_thread_t thread_id;
313 int status;
315 /* Valid mutex? */
316 if (! mutex)
317 return -1;
319 /* If we already own the lock then increment depth. */
320 thread_id = __gthread_objc_thread_id ();
321 if (mutex->owner == thread_id)
322 return ++mutex->depth;
324 /* Call the backend to lock the mutex. */
325 status = __gthread_objc_mutex_lock (mutex);
327 /* Failed? */
328 if (status)
329 return status;
331 /* Successfully locked the thread. */
332 mutex->owner = thread_id;
333 return mutex->depth = 1;
336 /* Try to grab a lock on a mutex. If this thread already has a lock
337 on this mutex then we increment the lock count and return it. If
338 another thread has a lock on the mutex returns -1. */
340 objc_mutex_trylock (objc_mutex_t mutex)
342 objc_thread_t thread_id;
343 int status;
345 /* Valid mutex? */
346 if (! mutex)
347 return -1;
349 /* If we already own the lock then increment depth. */
350 thread_id = __gthread_objc_thread_id ();
351 if (mutex->owner == thread_id)
352 return ++mutex->depth;
354 /* Call the backend to try to lock the mutex. */
355 status = __gthread_objc_mutex_trylock (mutex);
357 /* Failed? */
358 if (status)
359 return status;
361 /* Successfully locked the thread. */
362 mutex->owner = thread_id;
363 return mutex->depth = 1;
366 /* Unlocks the mutex by one level. Decrements the lock count on this
367 mutex by one. If the lock count reaches zero, release the lock on
368 the mutex. Returns the lock count on the mutex. It is an error to
369 attempt to unlock a mutex which this thread doesn't hold in which
370 case return -1 and the mutex is unaffected. */
372 objc_mutex_unlock (objc_mutex_t mutex)
374 objc_thread_t thread_id;
375 int status;
377 /* Valid mutex? */
378 if (! mutex)
379 return -1;
381 /* If another thread owns the lock then abort. */
382 thread_id = __gthread_objc_thread_id ();
383 if (mutex->owner != thread_id)
384 return -1;
386 /* Decrement depth and return. */
387 if (mutex->depth > 1)
388 return --mutex->depth;
390 /* Depth down to zero so we are no longer the owner. */
391 mutex->depth = 0;
392 mutex->owner = NULL;
394 /* Have the backend unlock the mutex. */
395 status = __gthread_objc_mutex_unlock (mutex);
397 /* Failed? */
398 if (status)
399 return status;
401 return 0;
404 /* Public condition mutex functions */
406 /* Allocate a condition. Return the condition pointer if successful
407 or NULL if the allocation failed for any reason. */
408 objc_condition_t
409 objc_condition_allocate (void)
411 objc_condition_t condition;
413 /* Allocate the condition mutex structure. */
414 if (! (condition =
415 (objc_condition_t) objc_malloc (sizeof (struct objc_condition))))
416 return NULL;
418 /* Call the backend to create the condition mutex. */
419 if (__gthread_objc_condition_allocate (condition))
421 /* Failed! */
422 objc_free (condition);
423 return NULL;
426 /* Success! */
427 return condition;
430 /* Deallocate a condition. Note that this includes an implicit
431 condition_broadcast to insure that waiting threads have the
432 opportunity to wake. It is legal to dealloc a condition only if no
433 other thread is/will be using it. Here we do NOT check for other
434 threads waiting but just wake them up. */
436 objc_condition_deallocate (objc_condition_t condition)
438 /* Broadcast the condition. */
439 if (objc_condition_broadcast (condition))
440 return -1;
442 /* Call the backend to destroy. */
443 if (__gthread_objc_condition_deallocate (condition))
444 return -1;
446 /* Free the condition mutex structure. */
447 objc_free (condition);
449 return 0;
452 /* Wait on the condition unlocking the mutex until
453 objc_condition_signal () or objc_condition_broadcast () are called
454 for the same condition. The given mutex *must* have the depth set
455 to 1 so that it can be unlocked here, so that someone else can lock
456 it and signal/broadcast the condition. The mutex is used to lock
457 access to the shared data that make up the "condition"
458 predicate. */
460 objc_condition_wait (objc_condition_t condition, objc_mutex_t mutex)
462 objc_thread_t thread_id;
464 /* Valid arguments? */
465 if (! mutex || ! condition)
466 return -1;
468 /* Make sure we are owner of mutex. */
469 thread_id = __gthread_objc_thread_id ();
470 if (mutex->owner != thread_id)
471 return -1;
473 /* Cannot be locked more than once. */
474 if (mutex->depth > 1)
475 return -1;
477 /* Virtually unlock the mutex. */
478 mutex->depth = 0;
479 mutex->owner = (objc_thread_t)NULL;
481 /* Call the backend to wait. */
482 __gthread_objc_condition_wait (condition, mutex);
484 /* Make ourselves owner of the mutex. */
485 mutex->owner = thread_id;
486 mutex->depth = 1;
488 return 0;
491 /* Wake up all threads waiting on this condition. It is recommended
492 that the called would lock the same mutex as the threads in
493 objc_condition_wait before changing the "condition predicate" and
494 make this call and unlock it right away after this call. */
496 objc_condition_broadcast (objc_condition_t condition)
498 /* Valid condition mutex? */
499 if (! condition)
500 return -1;
502 return __gthread_objc_condition_broadcast (condition);
505 /* Wake up one thread waiting on this condition. It is recommended
506 that the called would lock the same mutex as the threads in
507 objc_condition_wait before changing the "condition predicate" and
508 make this call and unlock it right away after this call. */
510 objc_condition_signal (objc_condition_t condition)
512 /* Valid condition mutex? */
513 if (! condition)
514 return -1;
516 return __gthread_objc_condition_signal (condition);
519 /* Make the objc thread system aware that a thread which is managed
520 (started, stopped) by external code could access objc facilities
521 from now on. This is used when you are interfacing with some
522 external non-objc-based environment/system - you must call
523 objc_thread_add () before an alien thread makes any calls to
524 Objective-C. Do not cause the _objc_became_multi_threaded hook to
525 be executed. */
526 void
527 objc_thread_add (void)
529 objc_mutex_lock (__objc_runtime_mutex);
530 __objc_is_multi_threaded = 1;
531 __objc_runtime_threads_alive++;
532 objc_mutex_unlock (__objc_runtime_mutex);
535 /* Make the objc thread system aware that a thread managed (started,
536 stopped) by some external code will no longer access objc and thus
537 can be forgotten by the objc thread system. Call
538 objc_thread_remove () when your alien thread is done with making
539 calls to Objective-C. */
540 void
541 objc_thread_remove (void)
543 objc_mutex_lock (__objc_runtime_mutex);
544 __objc_runtime_threads_alive--;
545 objc_mutex_unlock (__objc_runtime_mutex);