dbus/dbus-threads.c

   1 /* -*- mode: C; c-file-style: "gnu" -*- */
   2 /* dbus-threads.h  D-BUS threads handling
   3  *
   4  * Copyright (C) 2002, 2003 Red Hat Inc.
   5  *
   6  * Licensed under the Academic Free License version 1.2
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  *
  22  */
  23 #include "dbus-threads.h"
  24 #include "dbus-internals.h"
  25
  26 static DBusThreadFunctions thread_functions =
  27 {
  28   0,
  29   NULL, NULL, NULL, NULL,
  30   NULL, NULL, NULL, NULL, NULL,
  31
  32   NULL, NULL, NULL, NULL,
  33   NULL, NULL, NULL, NULL
  34 };
  35 static int thread_init_generation = 0;
  36
  37 /** This is used for the no-op default mutex pointer, just to be distinct from #NULL */
  38 #define _DBUS_DUMMY_MUTEX ((DBusMutex*)0xABCDEF)
  39
  40 /** This is used for the no-op default mutex pointer, just to be distinct from #NULL */
  41 #define _DBUS_DUMMY_CONDVAR ((DBusCondVar*)0xABCDEF2)
  42
  43 /**
  44  * @defgroup DBusThreads Thread functions
  45  * @ingroup  DBus
  46  * @brief dbus_threads_init(), dbus_mutex_lock(), etc.
  47  *
  48  * Functions and macros related to threads and thread locks.
  49  *
  50  * @{
  51  */
  52
  53 /**
  54  * Creates a new mutex using the function supplied to dbus_threads_init(),
  55  * or creates a no-op mutex if threads are not initialized.
  56  * May return #NULL even if threads are initialized, indicating
  57  * out-of-memory.
  58  *
  59  * @returns new mutex or #NULL
  60  */
  61 DBusMutex*
  62 dbus_mutex_new (void)
  63 {
  64   if (thread_functions.mutex_new)
  65     return (* thread_functions.mutex_new) ();
  66   else
  67     return _DBUS_DUMMY_MUTEX;
  68 }
  69
  70 /**
  71  * Frees a mutex created with dbus_mutex_new(); does
  72  * nothing if passed a #NULL pointer.
  73  */
  74 void
  75 dbus_mutex_free (DBusMutex *mutex)
  76 {
  77   if (mutex && thread_functions.mutex_free)
  78     (* thread_functions.mutex_free) (mutex);
  79 }
  80
  81 /**
  82  * Locks a mutex. Does nothing if passed a #NULL pointer.
  83  * Locks are not recursive.
  84  *
  85  * @returns #TRUE on success
  86  */
  87 dbus_bool_t
  88 dbus_mutex_lock (DBusMutex *mutex)
  89 {
  90   if (mutex && thread_functions.mutex_lock)
  91     return (* thread_functions.mutex_lock) (mutex);
  92   else
  93     return TRUE;
  94 }
  95
  96 /**
  97  * Unlocks a mutex. Does nothing if passed a #NULL pointer.
  98  *
  99  * @returns #TRUE on success
 100  */
 101 dbus_bool_t
 102 dbus_mutex_unlock (DBusMutex *mutex)
 103 {
 104   if (mutex && thread_functions.mutex_unlock)
 105     return (* thread_functions.mutex_unlock) (mutex);
 106   else
 107     return TRUE;
 108 }
 109
 110 /**
 111  * Creates a new condition variable using the function supplied
 112  * to dbus_threads_init(), or creates a no-op condition variable
 113  * if threads are not initialized. May return #NULL even if
 114  * threads are initialized, indicating out-of-memory.
 115  *
 116  * @returns new mutex or #NULL
 117  */
 118 DBusCondVar *
 119 dbus_condvar_new (void)
 120 {
 121   if (thread_functions.condvar_new)
 122     return (* thread_functions.condvar_new) ();
 123   else
 124     return _DBUS_DUMMY_CONDVAR;
 125 }
 126
 127 /**
 128  * Frees a conditional variable created with dbus_condvar_new(); does
 129  * nothing if passed a #NULL pointer.
 130  */
 131 void
 132 dbus_condvar_free (DBusCondVar *cond)
 133 {
 134   if (cond && thread_functions.condvar_free)
 135     (* thread_functions.condvar_free) (cond);
 136 }
 137
 138 /**
 139  * Atomically unlocks the mutex and waits for the conditions
 140  * variable to be signalled. Locks the mutex again before
 141  * returning.
 142  * Does nothing if passed a #NULL pointer.
 143  */
 144 void
 145 dbus_condvar_wait (DBusCondVar *cond,
 146                    DBusMutex   *mutex)
 147 {
 148   if (cond && mutex && thread_functions.condvar_wait)
 149     (* thread_functions.condvar_wait) (cond, mutex);
 150 }
 151
 152 /**
 153  * Atomically unlocks the mutex and waits for the conditions
 154  * variable to be signalled, or for a timeout. Locks the
 155  * mutex again before returning.
 156  * Does nothing if passed a #NULL pointer.
 157  *
 158  * @param cond the condition variable
 159  * @param mutex the mutex
 160  * @param timeout_milliseconds the maximum time to wait
 161  * @returns TRUE if the condition was reached, or FALSE if the
 162  * timeout was reached.
 163  */
 164 dbus_bool_t
 165 dbus_condvar_wait_timeout (DBusCondVar               *cond,
 166                            DBusMutex                 *mutex,
 167                            int                        timeout_milliseconds)
 168 {
 169   if (cond && mutex && thread_functions.condvar_wait)
 170     return (* thread_functions.condvar_wait_timeout) (cond, mutex, timeout_milliseconds);
 171   else
 172     return TRUE;
 173 }
 174
 175 /**
 176  * If there are threads waiting on the condition variable, wake
 177  * up exactly one.
 178  * Does nothing if passed a #NULL pointer.
 179  */
 180 void
 181 dbus_condvar_wake_one (DBusCondVar *cond)
 182 {
 183   if (cond && thread_functions.condvar_wake_one)
 184     (* thread_functions.condvar_wake_one) (cond);
 185 }
 186
 187 /**
 188  * If there are threads waiting on the condition variable, wake
 189  * up all of them.
 190  * Does nothing if passed a #NULL pointer.
 191  */
 192 void
 193 dbus_condvar_wake_all (DBusCondVar *cond)
 194 {
 195   if (cond && thread_functions.condvar_wake_all)
 196     (* thread_functions.condvar_wake_all) (cond);
 197 }
 198
 199 static void
 200 shutdown_global_locks (void *data)
 201 {
 202   DBusMutex ***locks = data;
 203   int i;
 204
 205   i = 0;
 206   while (i < _DBUS_N_GLOBAL_LOCKS)
 207     {
 208       dbus_mutex_free (*(locks[i]));
 209       *(locks[i]) = NULL;
 210       ++i;
 211     }
 212
 213   dbus_free (locks);
 214 }
 215
 216 static dbus_bool_t
 217 init_global_locks (void)
 218 {
 219   int i;
 220   DBusMutex ***dynamic_global_locks;
 221
 222   DBusMutex **global_locks[] = {
 223 #define LOCK_ADDR(name) (& _dbus_lock_##name)
 224     LOCK_ADDR (list),
 225     LOCK_ADDR (connection_slots),
 226     LOCK_ADDR (server_slots),
 227     LOCK_ADDR (message_slots),
 228     LOCK_ADDR (atomic),
 229     LOCK_ADDR (message_handler),
 230     LOCK_ADDR (callback_object),
 231     LOCK_ADDR (bus),
 232     LOCK_ADDR (shutdown_funcs),
 233     LOCK_ADDR (system_users)
 234 #undef LOCK_ADDR
 235   };
 236
 237   _dbus_assert (_DBUS_N_ELEMENTS (global_locks) ==
 238                 _DBUS_N_GLOBAL_LOCKS);
 239
 240   i = 0;
 241
 242   dynamic_global_locks = dbus_new (DBusMutex**, _DBUS_N_GLOBAL_LOCKS);
 243   if (dynamic_global_locks == NULL)
 244     goto failed;
 245
 246   while (i < _DBUS_N_ELEMENTS (global_locks))
 247     {
 248       *global_locks[i] = dbus_mutex_new ();
 249
 250       if (*global_locks[i] == NULL)
 251         goto failed;
 252
 253       dynamic_global_locks[i] = global_locks[i];
 254
 255       ++i;
 256     }
 257
 258   if (!_dbus_register_shutdown_func (shutdown_global_locks,
 259                                      dynamic_global_locks))
 260     goto failed;
 261
 262   return TRUE;
 263
 264  failed:
 265   dbus_free (dynamic_global_locks);
 266
 267   for (i = i - 1; i >= 0; i--)
 268     {
 269       dbus_mutex_free (*global_locks[i]);
 270       *global_locks[i] = NULL;
 271     }
 272   return FALSE;
 273 }
 274
 275
 276 /**
 277  * Initializes threads. If this function is not called,
 278  * the D-BUS library will not lock any data structures.
 279  * If it is called, D-BUS will do locking, at some cost
 280  * in efficiency. Note that this function must be called
 281  * BEFORE using any other D-BUS functions.
 282  *
 283  * This function may be called more than once, as long
 284  * as you pass in the same functions each time. If it's
 285  * called multiple times with different functions, then
 286  * a warning is printed, because someone is confused.
 287  *
 288  * @param functions functions for using threads
 289  * @returns #TRUE on success, #FALSE if no memory
 290  */
 291 dbus_bool_t
 292 dbus_threads_init (const DBusThreadFunctions *functions)
 293 {
 294   _dbus_assert (functions != NULL);
 295
 296   /* these base functions are required. Future additions to
 297    * DBusThreadFunctions may be optional.
 298    */
 299   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK);
 300   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK);
 301   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK);
 302   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK);
 303   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK);
 304   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK);
 305   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK);
 306   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK);
 307   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK);
 308   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK);
 309   _dbus_assert (functions->mutex_new != NULL);
 310   _dbus_assert (functions->mutex_free != NULL);
 311   _dbus_assert (functions->mutex_lock != NULL);
 312   _dbus_assert (functions->mutex_unlock != NULL);
 313   _dbus_assert (functions->condvar_new != NULL);
 314   _dbus_assert (functions->condvar_free != NULL);
 315   _dbus_assert (functions->condvar_wait != NULL);
 316   _dbus_assert (functions->condvar_wait_timeout != NULL);
 317   _dbus_assert (functions->condvar_wake_one != NULL);
 318   _dbus_assert (functions->condvar_wake_all != NULL);
 319
 320   /* Check that all bits in the mask actually are valid mask bits.
 321    * ensures people won't write code that breaks when we add
 322    * new bits.
 323    */
 324   _dbus_assert ((functions->mask & ~DBUS_THREAD_FUNCTIONS_ALL_MASK) == 0);
 325
 326   if (thread_init_generation != _dbus_current_generation)
 327     thread_functions.mask = 0; /* allow re-init in new generation */
 328
 329   if (thread_functions.mask != 0)
 330     {
 331       /* Silently allow multiple init if the functions are the same ones.
 332        * Well, we only bother checking two of them, just out of laziness.
 333        */
 334       if (thread_functions.mask == functions->mask &&
 335           thread_functions.mutex_new == functions->mutex_new &&
 336           thread_functions.condvar_new == functions->condvar_new)
 337         {
 338           return TRUE;
 339         }
 340       else
 341         {
 342           _dbus_warn ("dbus_threads_init() called twice with two different sets of functions\n");
 343           return FALSE;
 344         }
 345     }
 346
 347   thread_functions.mutex_new = functions->mutex_new;
 348   thread_functions.mutex_free = functions->mutex_free;
 349   thread_functions.mutex_lock = functions->mutex_lock;
 350   thread_functions.mutex_unlock = functions->mutex_unlock;
 351
 352   thread_functions.condvar_new = functions->condvar_new;
 353   thread_functions.condvar_free = functions->condvar_free;
 354   thread_functions.condvar_wait = functions->condvar_wait;
 355   thread_functions.condvar_wait_timeout = functions->condvar_wait_timeout;
 356   thread_functions.condvar_wake_one = functions->condvar_wake_one;
 357   thread_functions.condvar_wake_all = functions->condvar_wake_all;
 358
 359   thread_functions.mask = functions->mask;
 360
 361   if (!init_global_locks ())
 362     return FALSE;
 363
 364   thread_init_generation = _dbus_current_generation;
 365
 366   return TRUE;
 367 }
 368
 369 /** @} */
 370
 371 #ifdef DBUS_BUILD_TESTS
 372 /** Fake mutex used for debugging */
 373 typedef struct DBusFakeMutex DBusFakeMutex;
 374 /** Fake mutex used for debugging */
 375 struct DBusFakeMutex
 376 {
 377   dbus_bool_t locked; /**< Mutex is "locked" */
 378 };
 379
 380 static DBusMutex *  dbus_fake_mutex_new            (void);
 381 static void         dbus_fake_mutex_free           (DBusMutex   *mutex);
 382 static dbus_bool_t  dbus_fake_mutex_lock           (DBusMutex   *mutex);
 383 static dbus_bool_t  dbus_fake_mutex_unlock         (DBusMutex   *mutex);
 384 static DBusCondVar* dbus_fake_condvar_new          (void);
 385 static void         dbus_fake_condvar_free         (DBusCondVar *cond);
 386 static void         dbus_fake_condvar_wait         (DBusCondVar *cond,
 387                                                     DBusMutex   *mutex);
 388 static dbus_bool_t  dbus_fake_condvar_wait_timeout (DBusCondVar *cond,
 389                                                     DBusMutex   *mutex,
 390                                                     int          timeout_msec);
 391 static void         dbus_fake_condvar_wake_one     (DBusCondVar *cond);
 392 static void         dbus_fake_condvar_wake_all     (DBusCondVar *cond);
 393
 394
 395 static const DBusThreadFunctions fake_functions =
 396 {
 397   DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK |
 398   DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK |
 399   DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK |
 400   DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK |
 401   DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK |
 402   DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK |
 403   DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK |
 404   DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK |
 405   DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK|
 406   DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK,
 407   dbus_fake_mutex_new,
 408   dbus_fake_mutex_free,
 409   dbus_fake_mutex_lock,
 410   dbus_fake_mutex_unlock,
 411   dbus_fake_condvar_new,
 412   dbus_fake_condvar_free,
 413   dbus_fake_condvar_wait,
 414   dbus_fake_condvar_wait_timeout,
 415   dbus_fake_condvar_wake_one,
 416   dbus_fake_condvar_wake_all
 417 };
 418
 419 static DBusMutex *
 420 dbus_fake_mutex_new (void)
 421 {
 422   DBusFakeMutex *mutex;
 423
 424   mutex = dbus_new0 (DBusFakeMutex, 1);
 425
 426   return (DBusMutex *)mutex;
 427 }
 428
 429 static void
 430 dbus_fake_mutex_free (DBusMutex *mutex)
 431 {
 432   DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
 433
 434   _dbus_assert (!fake->locked);
 435
 436   dbus_free (fake);
 437 }
 438
 439 static dbus_bool_t
 440 dbus_fake_mutex_lock (DBusMutex *mutex)
 441 {
 442   DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
 443
 444   _dbus_assert (!fake->locked);
 445
 446   fake->locked = TRUE;
 447
 448   return TRUE;
 449 }
 450
 451 static dbus_bool_t
 452 dbus_fake_mutex_unlock (DBusMutex *mutex)
 453 {
 454   DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
 455
 456   _dbus_assert (fake->locked);
 457
 458   fake->locked = FALSE;
 459
 460   return TRUE;
 461 }
 462
 463 static DBusCondVar*
 464 dbus_fake_condvar_new (void)
 465 {
 466   return (DBusCondVar*) _dbus_strdup ("FakeCondvar");
 467 }
 468
 469 static void
 470 dbus_fake_condvar_free (DBusCondVar *cond)
 471 {
 472   dbus_free (cond);
 473 }
 474
 475 static void
 476 dbus_fake_condvar_wait (DBusCondVar *cond,
 477                         DBusMutex   *mutex)
 478 {
 479
 480 }
 481
 482 static dbus_bool_t
 483 dbus_fake_condvar_wait_timeout (DBusCondVar *cond,
 484                                 DBusMutex   *mutex,
 485                                 int         timeout_msec)
 486 {
 487   return TRUE;
 488 }
 489
 490 static void
 491 dbus_fake_condvar_wake_one (DBusCondVar *cond)
 492 {
 493
 494 }
 495
 496 static void
 497 dbus_fake_condvar_wake_all (DBusCondVar *cond)
 498 {
 499
 500 }
 501
 502 dbus_bool_t
 503 _dbus_threads_init_debug (void)
 504 {
 505   return dbus_threads_init (&fake_functions);
 506 }
 507
 508 #endif /* DBUS_BUILD_TESTS */