dbus/dbus-threads.c

   1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
   2 /* dbus-threads.h  D-Bus threads handling
   3  *
   4  * Copyright (C) 2002, 2003, 2006 Red Hat Inc.
   5  *
   6  * Licensed under the Academic Free License version 2.1
   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., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  21  *
  22  */
  23 #include <config.h>
  24 #include "dbus-threads.h"
  25 #include "dbus-internals.h"
  26 #include "dbus-threads-internal.h"
  27 #include "dbus-list.h"
  28
  29 static int thread_init_generation = 0;
  30
  31 /**
  32  * @defgroup DBusThreadsInternals Thread functions
  33  * @ingroup  DBusInternals
  34  * @brief _dbus_rmutex_lock(), etc.
  35  *
  36  * Functions and macros related to threads and thread locks.
  37  *
  38  * @{
  39  */
  40
  41 /**
  42  * Creates a new mutex
  43  * or creates a no-op mutex if threads are not initialized.
  44  * May return #NULL even if threads are initialized, indicating
  45  * out-of-memory.
  46  *
  47  * If possible, the mutex returned by this function is recursive, to
  48  * avoid deadlocks. However, that cannot be relied on.
  49  *
  50  * @param location_p the location of the new mutex, can return #NULL on OOM
  51  */
  52 void
  53 _dbus_rmutex_new_at_location (DBusRMutex **location_p)
  54 {
  55   _dbus_assert (location_p != NULL);
  56
  57   if (!dbus_threads_init_default ())
  58     {
  59       *location_p = NULL;
  60       return;
  61     }
  62
  63   *location_p = _dbus_platform_rmutex_new ();
  64 }
  65
  66 /**
  67  * Creates a new mutex
  68  * or creates a no-op mutex if threads are not initialized.
  69  * May return #NULL even if threads are initialized, indicating
  70  * out-of-memory.
  71  *
  72  * The returned mutex is suitable for use with condition variables.
  73  *
  74  * @param location_p the location of the new mutex, can return #NULL on OOM
  75  */
  76 void
  77 _dbus_cmutex_new_at_location (DBusCMutex **location_p)
  78 {
  79   _dbus_assert (location_p != NULL);
  80
  81   if (!dbus_threads_init_default ())
  82     {
  83       *location_p = NULL;
  84       return;
  85     }
  86
  87   *location_p = _dbus_platform_cmutex_new ();
  88 }
  89
  90 /**
  91  * Frees a DBusRMutex; does nothing if passed a #NULL pointer.
  92  */
  93 void
  94 _dbus_rmutex_free_at_location (DBusRMutex **location_p)
  95 {
  96   if (location_p == NULL)
  97     return;
  98
  99   if (*location_p != NULL)
 100     _dbus_platform_rmutex_free (*location_p);
 101 }
 102
 103 /**
 104  * Frees a DBusCMutex; does nothing if passed a #NULL pointer.
 105  */
 106 void
 107 _dbus_cmutex_free_at_location (DBusCMutex **location_p)
 108 {
 109   if (location_p == NULL)
 110     return;
 111
 112   if (*location_p != NULL)
 113     _dbus_platform_cmutex_free (*location_p);
 114 }
 115
 116 /**
 117  * Locks a mutex. Does nothing if passed a #NULL pointer.
 118  * Locks may be recursive if threading implementation initialized
 119  * recursive locks.
 120  */
 121 void
 122 _dbus_rmutex_lock (DBusRMutex *mutex)
 123 {
 124   if (mutex == NULL)
 125     return;
 126
 127   _dbus_platform_rmutex_lock (mutex);
 128 }
 129
 130 /**
 131  * Locks a mutex. Does nothing if passed a #NULL pointer.
 132  * Locks may be recursive if threading implementation initialized
 133  * recursive locks.
 134  */
 135 void
 136 _dbus_cmutex_lock (DBusCMutex *mutex)
 137 {
 138   if (mutex == NULL)
 139     return;
 140
 141   _dbus_platform_cmutex_lock (mutex);
 142 }
 143
 144 /**
 145  * Unlocks a mutex. Does nothing if passed a #NULL pointer.
 146  *
 147  * @returns #TRUE on success
 148  */
 149 void
 150 _dbus_rmutex_unlock (DBusRMutex *mutex)
 151 {
 152   if (mutex == NULL)
 153     return;
 154
 155   _dbus_platform_rmutex_unlock (mutex);
 156 }
 157
 158 /**
 159  * Unlocks a mutex. Does nothing if passed a #NULL pointer.
 160  *
 161  * @returns #TRUE on success
 162  */
 163 void
 164 _dbus_cmutex_unlock (DBusCMutex *mutex)
 165 {
 166   if (mutex == NULL)
 167     return;
 168
 169   _dbus_platform_cmutex_unlock (mutex);
 170 }
 171
 172 /**
 173  * Creates a new condition variable using the function supplied
 174  * to dbus_threads_init(), or creates a no-op condition variable
 175  * if threads are not initialized. May return #NULL even if
 176  * threads are initialized, indicating out-of-memory.
 177  *
 178  * @returns new mutex or #NULL
 179  */
 180 DBusCondVar *
 181 _dbus_condvar_new (void)
 182 {
 183   if (!dbus_threads_init_default ())
 184     return NULL;
 185
 186   return _dbus_platform_condvar_new ();
 187 }
 188
 189
 190 /**
 191  * This does the same thing as _dbus_condvar_new.  It however
 192  * gives another level of indirection by allocating a pointer
 193  * to point to the condvar location; this used to be useful.
 194  *
 195  * @returns the location of a new condvar or #NULL on OOM
 196  */
 197
 198 void
 199 _dbus_condvar_new_at_location (DBusCondVar **location_p)
 200 {
 201   _dbus_assert (location_p != NULL);
 202
 203   *location_p = _dbus_condvar_new();
 204 }
 205
 206
 207 /**
 208  * Frees a conditional variable created with dbus_condvar_new(); does
 209  * nothing if passed a #NULL pointer.
 210  */
 211 void
 212 _dbus_condvar_free (DBusCondVar *cond)
 213 {
 214   if (cond == NULL)
 215     return;
 216
 217   _dbus_platform_condvar_free (cond);
 218 }
 219
 220 /**
 221  * Frees a condition variable; does nothing if passed a #NULL pointer.
 222  */
 223 void
 224 _dbus_condvar_free_at_location (DBusCondVar **location_p)
 225 {
 226   if (location_p == NULL)
 227     return;
 228
 229   if (*location_p != NULL)
 230     _dbus_platform_condvar_free (*location_p);
 231 }
 232
 233 /**
 234  * Atomically unlocks the mutex and waits for the conditions
 235  * variable to be signalled. Locks the mutex again before
 236  * returning.
 237  * Does nothing if passed a #NULL pointer.
 238  */
 239 void
 240 _dbus_condvar_wait (DBusCondVar *cond,
 241                     DBusCMutex  *mutex)
 242 {
 243   if (cond == NULL || mutex == NULL)
 244     return;
 245
 246   _dbus_platform_condvar_wait (cond, mutex);
 247 }
 248
 249 /**
 250  * Atomically unlocks the mutex and waits for the conditions variable
 251  * to be signalled, or for a timeout. Locks the mutex again before
 252  * returning.  Does nothing if passed a #NULL pointer.  Return value
 253  * is #FALSE if we timed out, #TRUE otherwise.
 254  *
 255  * @param cond the condition variable
 256  * @param mutex the mutex
 257  * @param timeout_milliseconds the maximum time to wait
 258  * @returns #FALSE if the timeout occurred, #TRUE if not
 259  */
 260 dbus_bool_t
 261 _dbus_condvar_wait_timeout (DBusCondVar               *cond,
 262                             DBusCMutex                *mutex,
 263                             int                        timeout_milliseconds)
 264 {
 265   if (cond == NULL || mutex == NULL)
 266     return TRUE;
 267
 268   return _dbus_platform_condvar_wait_timeout (cond, mutex,
 269       timeout_milliseconds);
 270 }
 271
 272 /**
 273  * If there are threads waiting on the condition variable, wake
 274  * up exactly one.
 275  * Does nothing if passed a #NULL pointer.
 276  */
 277 void
 278 _dbus_condvar_wake_one (DBusCondVar *cond)
 279 {
 280   if (cond == NULL)
 281     return;
 282
 283   _dbus_platform_condvar_wake_one (cond);
 284 }
 285
 286 static DBusRMutex *global_locks[_DBUS_N_GLOBAL_LOCKS] = { NULL };
 287
 288 static void
 289 shutdown_global_locks (void *nil)
 290 {
 291   int i;
 292
 293   for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
 294     {
 295       _dbus_assert (global_locks[i] != NULL);
 296       _dbus_platform_rmutex_free (global_locks[i]);
 297       global_locks[i] = NULL;
 298     }
 299 }
 300
 301 static dbus_bool_t
 302 init_global_locks (void)
 303 {
 304   int i;
 305   dbus_bool_t ok;
 306
 307   for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
 308     {
 309       _dbus_assert (global_locks[i] == NULL);
 310
 311       global_locks[i] = _dbus_platform_rmutex_new ();
 312
 313       if (global_locks[i] == NULL)
 314         goto failed;
 315     }
 316
 317   _dbus_platform_rmutex_lock (global_locks[_DBUS_LOCK_shutdown_funcs]);
 318   ok = _dbus_register_shutdown_func_unlocked (shutdown_global_locks, NULL);
 319   _dbus_platform_rmutex_unlock (global_locks[_DBUS_LOCK_shutdown_funcs]);
 320
 321   if (!ok)
 322     goto failed;
 323
 324   return TRUE;
 325
 326  failed:
 327   for (i = i - 1; i >= 0; i--)
 328     {
 329       _dbus_platform_rmutex_free (global_locks[i]);
 330       global_locks[i] = NULL;
 331     }
 332
 333   return FALSE;
 334 }
 335
 336 dbus_bool_t
 337 _dbus_lock (DBusGlobalLock lock)
 338 {
 339   _dbus_assert (lock >= 0);
 340   _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
 341
 342   if (thread_init_generation != _dbus_current_generation &&
 343       !dbus_threads_init_default ())
 344     return FALSE;
 345
 346   _dbus_platform_rmutex_lock (global_locks[lock]);
 347   return TRUE;
 348 }
 349
 350 void
 351 _dbus_unlock (DBusGlobalLock lock)
 352 {
 353   _dbus_assert (lock >= 0);
 354   _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
 355
 356   _dbus_platform_rmutex_unlock (global_locks[lock]);
 357 }
 358
 359 /** @} */ /* end of internals */
 360
 361 /**
 362  * @defgroup DBusThreads Thread functions
 363  * @ingroup  DBus
 364  * @brief dbus_threads_init() and dbus_threads_init_default()
 365  *
 366  * Functions and macros related to threads and thread locks.
 367  *
 368  * If threads are initialized, the D-Bus library has locks on all
 369  * global data structures.  In addition, each #DBusConnection has a
 370  * lock, so only one thread at a time can touch the connection.  (See
 371  * @ref DBusConnection for more on connection locking.)
 372  *
 373  * Most other objects, however, do not have locks - they can only be
 374  * used from a single thread at a time, unless you lock them yourself.
 375  * For example, a #DBusMessage can't be modified from two threads
 376  * at once.
 377  *
 378  * @{
 379  */
 380
 381 /**
 382  * Initializes threads, like dbus_threads_init_default().
 383  * This version previously allowed user-specified threading
 384  * primitives, but since D-Bus 1.6 it ignores them and behaves
 385  * exactly like dbus_threads_init_default().
 386  *
 387  * @param functions ignored, formerly functions for using threads
 388  * @returns #TRUE on success, #FALSE if no memory
 389  */
 390 dbus_bool_t
 391 dbus_threads_init (const DBusThreadFunctions *functions)
 392 {
 393   _dbus_threads_lock_platform_specific ();
 394
 395   if (thread_init_generation == _dbus_current_generation)
 396     {
 397       _dbus_threads_unlock_platform_specific ();
 398       return TRUE;
 399     }
 400
 401   if (!_dbus_threads_init_platform_specific() ||
 402       !init_global_locks ())
 403     {
 404       _dbus_threads_unlock_platform_specific ();
 405       return FALSE;
 406     }
 407
 408   thread_init_generation = _dbus_current_generation;
 409
 410   _dbus_threads_unlock_platform_specific ();
 411   return TRUE;
 412 }
 413
 414
 415
 416 /* Default thread implemenation */
 417
 418 /**
 419  * Initializes threads. If this function is not called, the D-Bus
 420  * library will not lock any data structures.  If it is called, D-Bus
 421  * will do locking, at some cost in efficiency.
 422  *
 423  * Since D-Bus 1.7 it is safe to call this function from any thread,
 424  * any number of times (but it must be called before any other
 425  * libdbus API is used).
 426  *
 427  * In D-Bus 1.6 or older, this function must be called in the main thread
 428  * before any other thread starts. As a result, it is not sufficient to
 429  * call this function in a library or plugin, unless the library or plugin
 430  * imposes a similar requirement on its callers.
 431  *
 432  * dbus_shutdown() reverses the effects of this function when it
 433  * resets all global state in libdbus.
 434  *
 435  * @returns #TRUE on success, #FALSE if not enough memory
 436  */
 437 dbus_bool_t
 438 dbus_threads_init_default (void)
 439 {
 440   return dbus_threads_init (NULL);
 441 }
 442
 443
 444 /** @} */
 445
 446 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
 447
 448 dbus_bool_t
 449 _dbus_threads_init_debug (void)
 450 {
 451   return dbus_threads_init (NULL);
 452 }
 453
 454 #endif /* DBUS_ENABLE_EMBEDDED_TESTS */