libobjc/thr.c

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