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 #ifdef DBUS_HAVE_STATIC_RECURSIVE_MUTEXES
 287
 288 static dbus_bool_t
 289 init_global_locks (void)
 290 {
 291   return TRUE;
 292 }
 293
 294 /* implementations in dbus-sysdeps-pthread.c */
 295
 296 #else /* !defined(DBUS_HAVE_STATIC_RECURSIVE_MUTEXES) */
 297
 298 static DBusRMutex *global_locks[_DBUS_N_GLOBAL_LOCKS] = { NULL };
 299
 300 static void
 301 shutdown_global_locks (void *nil)
 302 {
 303   int i;
 304
 305   for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
 306     {
 307       _dbus_assert (global_locks[i] != NULL);
 308       _dbus_platform_rmutex_free (global_locks[i]);
 309       global_locks[i] = NULL;
 310     }
 311 }
 312
 313 static dbus_bool_t
 314 init_global_locks (void)
 315 {
 316   int i;
 317   dbus_bool_t ok;
 318
 319   for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
 320     {
 321       _dbus_assert (global_locks[i] == NULL);
 322
 323       global_locks[i] = _dbus_platform_rmutex_new ();
 324
 325       if (global_locks[i] == NULL)
 326         goto failed;
 327     }
 328
 329   _dbus_platform_rmutex_lock (global_locks[_DBUS_LOCK_shutdown_funcs]);
 330   ok = _dbus_register_shutdown_func_unlocked (shutdown_global_locks, NULL);
 331   _dbus_platform_rmutex_unlock (global_locks[_DBUS_LOCK_shutdown_funcs]);
 332
 333   if (!ok)
 334     goto failed;
 335
 336   return TRUE;
 337
 338  failed:
 339   for (i = i - 1; i >= 0; i--)
 340     {
 341       _dbus_platform_rmutex_free (global_locks[i]);
 342       global_locks[i] = NULL;
 343     }
 344
 345   return FALSE;
 346 }
 347
 348 dbus_bool_t
 349 _dbus_lock (DBusGlobalLock lock)
 350 {
 351   _dbus_assert (lock >= 0);
 352   _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
 353
 354   if (thread_init_generation != _dbus_current_generation &&
 355       !dbus_threads_init_default ())
 356     return FALSE;
 357
 358   _dbus_platform_rmutex_lock (global_locks[lock]);
 359   return TRUE;
 360 }
 361
 362 void
 363 _dbus_unlock (DBusGlobalLock lock)
 364 {
 365   _dbus_assert (lock >= 0);
 366   _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
 367
 368   _dbus_platform_rmutex_unlock (global_locks[lock]);
 369 }
 370
 371 #endif /* !defined(DBUS_HAVE_STATIC_RECURSIVE_MUTEXES) */
 372
 373 /** @} */ /* end of internals */
 374
 375 /**
 376  * @defgroup DBusThreads Thread functions
 377  * @ingroup  DBus
 378  * @brief dbus_threads_init() and dbus_threads_init_default()
 379  *
 380  * Functions and macros related to threads and thread locks.
 381  *
 382  * If threads are initialized, the D-Bus library has locks on all
 383  * global data structures.  In addition, each #DBusConnection has a
 384  * lock, so only one thread at a time can touch the connection.  (See
 385  * @ref DBusConnection for more on connection locking.)
 386  *
 387  * Most other objects, however, do not have locks - they can only be
 388  * used from a single thread at a time, unless you lock them yourself.
 389  * For example, a #DBusMessage can't be modified from two threads
 390  * at once.
 391  *
 392  * @{
 393  */
 394
 395 /**
 396  * Initializes threads, like dbus_threads_init_default().
 397  * This version previously allowed user-specified threading
 398  * primitives, but since D-Bus 1.6 it ignores them and behaves
 399  * exactly like dbus_threads_init_default().
 400  *
 401  * @param functions ignored, formerly functions for using threads
 402  * @returns #TRUE on success, #FALSE if no memory
 403  */
 404 dbus_bool_t
 405 dbus_threads_init (const DBusThreadFunctions *functions)
 406 {
 407   _dbus_threads_lock_platform_specific ();
 408
 409   if (thread_init_generation == _dbus_current_generation)
 410     {
 411       _dbus_threads_unlock_platform_specific ();
 412       return TRUE;
 413     }
 414
 415   if (!_dbus_threads_init_platform_specific() ||
 416       !init_global_locks ())
 417     {
 418       _dbus_threads_unlock_platform_specific ();
 419       return FALSE;
 420     }
 421
 422   thread_init_generation = _dbus_current_generation;
 423
 424   _dbus_threads_unlock_platform_specific ();
 425   return TRUE;
 426 }
 427
 428
 429
 430 /* Default thread implemenation */
 431
 432 /**
 433  * Initializes threads. If this function is not called, the D-Bus
 434  * library will not lock any data structures.  If it is called, D-Bus
 435  * will do locking, at some cost in efficiency.
 436  *
 437  * Since D-Bus 1.7 it is safe to call this function from any thread,
 438  * any number of times (but it must be called before any other
 439  * libdbus API is used).
 440  *
 441  * In D-Bus 1.6 or older, this function must be called in the main thread
 442  * before any other thread starts. As a result, it is not sufficient to
 443  * call this function in a library or plugin, unless the library or plugin
 444  * imposes a similar requirement on its callers.
 445  *
 446  * dbus_shutdown() reverses the effects of this function when it
 447  * resets all global state in libdbus.
 448  *
 449  * @returns #TRUE on success, #FALSE if not enough memory
 450  */
 451 dbus_bool_t
 452 dbus_threads_init_default (void)
 453 {
 454   return dbus_threads_init (NULL);
 455 }
 456
 457
 458 /** @} */
 459
 460 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
 461
 462 dbus_bool_t
 463 _dbus_threads_init_debug (void)
 464 {
 465   return dbus_threads_init (NULL);
 466 }
 467
 468 #endif /* DBUS_ENABLE_EMBEDDED_TESTS */