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 DBusThreadFunctions thread_functions =
  30 {
  31   0,
  32   NULL, NULL, NULL, NULL, NULL,
  33   NULL, NULL, NULL, NULL, NULL,
  34   NULL, NULL, NULL, NULL,
  35
  36   NULL, NULL, NULL, NULL
  37 };
  38
  39 static int thread_init_generation = 0;
  40
  41 static DBusList *uninitialized_rmutex_list = NULL;
  42 static DBusList *uninitialized_cmutex_list = NULL;
  43 static DBusList *uninitialized_condvar_list = NULL;
  44
  45 /** This is used for the no-op default mutex pointer, just to be distinct from #NULL */
  46 #define _DBUS_DUMMY_MUTEX ((DBusMutex*)0xABCDEF)
  47
  48 /** This is used for the no-op default mutex pointer, just to be distinct from #NULL */
  49 #define _DBUS_DUMMY_CONDVAR ((DBusCondVar*)0xABCDEF2)
  50
  51 static void _dbus_mutex_free (DBusMutex *mutex, DBusMutexFreeFunction dtor);
  52 static void _dbus_mutex_new_at_location (DBusMutex            **location_p,
  53                                          DBusMutexNewFunction   ctor,
  54                                          DBusMutexFreeFunction  dtor,
  55                                          DBusList             **uninitialized);
  56 static void _dbus_mutex_free_at_location (DBusMutex            **location_p,
  57                                           DBusMutexFreeFunction  dtor,
  58                                           DBusList             **uninitialized);
  59
  60 /**
  61  * @defgroup DBusThreadsInternals Thread functions
  62  * @ingroup  DBusInternals
  63  * @brief _dbus_rmutex_lock(), etc.
  64  *
  65  * Functions and macros related to threads and thread locks.
  66  *
  67  * @{
  68  */
  69
  70 static DBusMutex *
  71 _dbus_mutex_new (DBusMutexNewFunction ctor)
  72 {
  73   if (ctor)
  74     return ctor ();
  75   else if (thread_functions.recursive_mutex_new)
  76     return (* thread_functions.recursive_mutex_new) ();
  77   else if (thread_functions.mutex_new)
  78     return (* thread_functions.mutex_new) ();
  79   else
  80     return _DBUS_DUMMY_MUTEX;
  81 }
  82
  83 /**
  84  * Creates a new mutex using the function supplied to dbus_threads_init(),
  85  * or creates a no-op mutex if threads are not initialized.
  86  * May return #NULL even if threads are initialized, indicating
  87  * out-of-memory.
  88  *
  89  * If possible, the mutex returned by this function is recursive, to
  90  * avoid deadlocks. However, that cannot be relied on.
  91  *
  92  * The extra level of indirection given by allocating a pointer
  93  * to point to the mutex location allows the threading
  94  * module to swap out dummy mutexes for real a real mutex so libraries
  95  * can initialize threads even after the D-Bus API has been used.
  96  *
  97  * @param location_p the location of the new mutex, can return #NULL on OOM
  98  */
  99 void
 100 _dbus_rmutex_new_at_location (DBusRMutex **location_p)
 101 {
 102   _dbus_mutex_new_at_location ((DBusMutex **) location_p,
 103                                thread_functions.recursive_mutex_new,
 104                                thread_functions.recursive_mutex_free,
 105                                &uninitialized_rmutex_list);
 106 }
 107
 108 /**
 109  * Creates a new mutex using the function supplied to dbus_threads_init(),
 110  * or creates a no-op mutex if threads are not initialized.
 111  * May return #NULL even if threads are initialized, indicating
 112  * out-of-memory.
 113  *
 114  * The returned mutex is suitable for use with condition variables.
 115  *
 116  * The extra level of indirection given by allocating a pointer
 117  * to point to the mutex location allows the threading
 118  * module to swap out dummy mutexes for real a real mutex so libraries
 119  * can initialize threads even after the D-Bus API has been used.
 120  *
 121  * @param location_p the location of the new mutex, can return #NULL on OOM
 122  */
 123 void
 124 _dbus_cmutex_new_at_location (DBusCMutex **location_p)
 125 {
 126   _dbus_mutex_new_at_location ((DBusMutex **) location_p,
 127                                thread_functions.mutex_new,
 128                                thread_functions.mutex_free,
 129                                &uninitialized_cmutex_list);
 130 }
 131
 132 static void
 133 _dbus_mutex_new_at_location (DBusMutex            **location_p,
 134                              DBusMutexNewFunction   ctor,
 135                              DBusMutexFreeFunction  dtor,
 136                              DBusList             **uninitialized)
 137 {
 138   _dbus_assert (location_p != NULL);
 139
 140   *location_p = _dbus_mutex_new (ctor);
 141
 142   if (thread_init_generation != _dbus_current_generation && *location_p)
 143     {
 144       if (!_dbus_list_append (uninitialized, location_p))
 145         {
 146           _dbus_mutex_free (*location_p, dtor);
 147           *location_p = NULL;
 148         }
 149     }
 150 }
 151
 152 static void
 153 _dbus_mutex_free (DBusMutex             *mutex,
 154                   DBusMutexFreeFunction  dtor)
 155 {
 156   if (mutex)
 157     {
 158       if (dtor)
 159         dtor (mutex);
 160       else if (mutex && thread_functions.recursive_mutex_free)
 161         (* thread_functions.recursive_mutex_free) (mutex);
 162       else if (mutex && thread_functions.mutex_free)
 163         (* thread_functions.mutex_free) (mutex);
 164     }
 165 }
 166
 167 static void
 168 _dbus_mutex_free_at_location (DBusMutex            **location_p,
 169                               DBusMutexFreeFunction  dtor,
 170                               DBusList             **uninitialized)
 171 {
 172   if (location_p)
 173     {
 174       if (thread_init_generation != _dbus_current_generation)
 175         _dbus_list_remove (uninitialized, location_p);
 176
 177       _dbus_mutex_free (*location_p, dtor);
 178     }
 179 }
 180
 181 /**
 182  * Frees a DBusRMutex and removes it from the
 183  * uninitialized mutex list;
 184  * does nothing if passed a #NULL pointer.
 185  */
 186 void
 187 _dbus_rmutex_free_at_location (DBusRMutex **location_p)
 188 {
 189   _dbus_mutex_free_at_location ((DBusMutex **) location_p,
 190                                 thread_functions.recursive_mutex_free,
 191                                 &uninitialized_rmutex_list);
 192 }
 193
 194 /**
 195  * Frees a DBusCMutex and removes it from the
 196  * uninitialized mutex list;
 197  * does nothing if passed a #NULL pointer.
 198  */
 199 void
 200 _dbus_cmutex_free_at_location (DBusCMutex **location_p)
 201 {
 202   _dbus_mutex_free_at_location ((DBusMutex **) location_p,
 203                                 thread_functions.mutex_free,
 204                                 &uninitialized_cmutex_list);
 205 }
 206
 207 /**
 208  * Locks a mutex. Does nothing if passed a #NULL pointer.
 209  * Locks may be recursive if threading implementation initialized
 210  * recursive locks.
 211  */
 212 void
 213 _dbus_rmutex_lock (DBusRMutex *mutex)
 214 {
 215   if (mutex)
 216     {
 217       if (thread_functions.recursive_mutex_lock)
 218         (* thread_functions.recursive_mutex_lock) ((DBusMutex *) mutex);
 219       else if (thread_functions.mutex_lock)
 220         (* thread_functions.mutex_lock) ((DBusMutex *) mutex);
 221     }
 222 }
 223
 224 /**
 225  * Locks a mutex. Does nothing if passed a #NULL pointer.
 226  * Locks may be recursive if threading implementation initialized
 227  * recursive locks.
 228  */
 229 void
 230 _dbus_cmutex_lock (DBusCMutex *mutex)
 231 {
 232   if (mutex)
 233     {
 234       if (thread_functions.mutex_lock)
 235         (* thread_functions.mutex_lock) ((DBusMutex *) mutex);
 236       else if (thread_functions.recursive_mutex_lock)
 237         (* thread_functions.recursive_mutex_lock) ((DBusMutex *) mutex);
 238     }
 239 }
 240
 241 /**
 242  * Unlocks a mutex. Does nothing if passed a #NULL pointer.
 243  *
 244  * @returns #TRUE on success
 245  */
 246 void
 247 _dbus_rmutex_unlock (DBusRMutex *mutex)
 248 {
 249   if (mutex)
 250     {
 251       if (thread_functions.recursive_mutex_unlock)
 252         (* thread_functions.recursive_mutex_unlock) ((DBusMutex *) mutex);
 253       else if (thread_functions.mutex_unlock)
 254         (* thread_functions.mutex_unlock) ((DBusMutex *) mutex);
 255     }
 256 }
 257
 258 /**
 259  * Unlocks a mutex. Does nothing if passed a #NULL pointer.
 260  *
 261  * @returns #TRUE on success
 262  */
 263 void
 264 _dbus_cmutex_unlock (DBusCMutex *mutex)
 265 {
 266   if (mutex)
 267     {
 268       if (thread_functions.mutex_unlock)
 269         (* thread_functions.mutex_unlock) ((DBusMutex *) mutex);
 270       else if (thread_functions.recursive_mutex_unlock)
 271         (* thread_functions.recursive_mutex_unlock) ((DBusMutex *) mutex);
 272     }
 273 }
 274
 275 /**
 276  * Creates a new condition variable using the function supplied
 277  * to dbus_threads_init(), or creates a no-op condition variable
 278  * if threads are not initialized. May return #NULL even if
 279  * threads are initialized, indicating out-of-memory.
 280  *
 281  * @returns new mutex or #NULL
 282  */
 283 DBusCondVar *
 284 _dbus_condvar_new (void)
 285 {
 286   if (thread_functions.condvar_new)
 287     return (* thread_functions.condvar_new) ();
 288   else
 289     return _DBUS_DUMMY_CONDVAR;
 290 }
 291
 292
 293 /**
 294  * This does the same thing as _dbus_condvar_new.  It however
 295  * gives another level of indirection by allocating a pointer
 296  * to point to the condvar location.  This allows the threading
 297  * module to swap out dummy condvars for real a real condvar so libraries
 298  * can initialize threads even after the D-Bus API has been used.
 299  *
 300  * @returns the location of a new condvar or #NULL on OOM
 301  */
 302
 303 void
 304 _dbus_condvar_new_at_location (DBusCondVar **location_p)
 305 {
 306   *location_p = _dbus_condvar_new();
 307
 308   if (thread_init_generation != _dbus_current_generation && *location_p)
 309     {
 310       if (!_dbus_list_append (&uninitialized_condvar_list, location_p))
 311         {
 312           _dbus_condvar_free (*location_p);
 313           *location_p = NULL;
 314         }
 315     }
 316 }
 317
 318
 319 /**
 320  * Frees a conditional variable created with dbus_condvar_new(); does
 321  * nothing if passed a #NULL pointer.
 322  */
 323 void
 324 _dbus_condvar_free (DBusCondVar *cond)
 325 {
 326   if (cond && thread_functions.condvar_free)
 327     (* thread_functions.condvar_free) (cond);
 328 }
 329
 330 /**
 331  * Frees a conditional variable and removes it from the
 332  * uninitialized_condvar_list;
 333  * does nothing if passed a #NULL pointer.
 334  */
 335 void
 336 _dbus_condvar_free_at_location (DBusCondVar **location_p)
 337 {
 338   if (location_p)
 339     {
 340       if (thread_init_generation != _dbus_current_generation)
 341         _dbus_list_remove (&uninitialized_condvar_list, location_p);
 342
 343       _dbus_condvar_free (*location_p);
 344     }
 345 }
 346
 347 /**
 348  * Atomically unlocks the mutex and waits for the conditions
 349  * variable to be signalled. Locks the mutex again before
 350  * returning.
 351  * Does nothing if passed a #NULL pointer.
 352  */
 353 void
 354 _dbus_condvar_wait (DBusCondVar *cond,
 355                     DBusCMutex  *mutex)
 356 {
 357   if (cond && mutex && thread_functions.condvar_wait)
 358     (* thread_functions.condvar_wait) (cond, (DBusMutex *) mutex);
 359 }
 360
 361 /**
 362  * Atomically unlocks the mutex and waits for the conditions variable
 363  * to be signalled, or for a timeout. Locks the mutex again before
 364  * returning.  Does nothing if passed a #NULL pointer.  Return value
 365  * is #FALSE if we timed out, #TRUE otherwise.
 366  *
 367  * @param cond the condition variable
 368  * @param mutex the mutex
 369  * @param timeout_milliseconds the maximum time to wait
 370  * @returns #FALSE if the timeout occurred, #TRUE if not
 371  */
 372 dbus_bool_t
 373 _dbus_condvar_wait_timeout (DBusCondVar               *cond,
 374                             DBusCMutex                *mutex,
 375                             int                        timeout_milliseconds)
 376 {
 377   if (cond && mutex && thread_functions.condvar_wait)
 378     return (* thread_functions.condvar_wait_timeout) (cond,
 379                                                       (DBusMutex *) mutex,
 380                                                       timeout_milliseconds);
 381   else
 382     return TRUE;
 383 }
 384
 385 /**
 386  * If there are threads waiting on the condition variable, wake
 387  * up exactly one.
 388  * Does nothing if passed a #NULL pointer.
 389  */
 390 void
 391 _dbus_condvar_wake_one (DBusCondVar *cond)
 392 {
 393   if (cond && thread_functions.condvar_wake_one)
 394     (* thread_functions.condvar_wake_one) (cond);
 395 }
 396
 397 /**
 398  * If there are threads waiting on the condition variable, wake
 399  * up all of them.
 400  * Does nothing if passed a #NULL pointer.
 401  */
 402 void
 403 _dbus_condvar_wake_all (DBusCondVar *cond)
 404 {
 405   if (cond && thread_functions.condvar_wake_all)
 406     (* thread_functions.condvar_wake_all) (cond);
 407 }
 408
 409 static void
 410 shutdown_global_locks (void *data)
 411 {
 412   DBusMutex ***locks = data;
 413   int i;
 414
 415   i = 0;
 416   while (i < _DBUS_N_GLOBAL_LOCKS)
 417     {
 418       _dbus_mutex_free (*(locks[i]), thread_functions.recursive_mutex_free);
 419       *(locks[i]) = NULL;
 420       ++i;
 421     }
 422
 423   dbus_free (locks);
 424 }
 425
 426 static void
 427 shutdown_uninitialized_locks (void *data)
 428 {
 429   _dbus_list_clear (&uninitialized_rmutex_list);
 430   _dbus_list_clear (&uninitialized_cmutex_list);
 431   _dbus_list_clear (&uninitialized_condvar_list);
 432 }
 433
 434 static dbus_bool_t
 435 init_uninitialized_locks (void)
 436 {
 437   DBusList *link;
 438
 439   _dbus_assert (thread_init_generation != _dbus_current_generation);
 440
 441   link = uninitialized_rmutex_list;
 442   while (link != NULL)
 443     {
 444       DBusMutex **mp;
 445
 446       mp = link->data;
 447       _dbus_assert (*mp == _DBUS_DUMMY_MUTEX);
 448
 449       *mp = _dbus_mutex_new (thread_functions.recursive_mutex_new);
 450       if (*mp == NULL)
 451         goto fail_mutex;
 452
 453       link = _dbus_list_get_next_link (&uninitialized_rmutex_list, link);
 454     }
 455
 456   link = uninitialized_cmutex_list;
 457   while (link != NULL)
 458     {
 459       DBusMutex **mp;
 460
 461       mp = link->data;
 462       _dbus_assert (*mp == _DBUS_DUMMY_MUTEX);
 463
 464       *mp = _dbus_mutex_new (thread_functions.mutex_new);
 465       if (*mp == NULL)
 466         goto fail_mutex;
 467
 468       link = _dbus_list_get_next_link (&uninitialized_cmutex_list, link);
 469     }
 470
 471   link = uninitialized_condvar_list;
 472   while (link != NULL)
 473     {
 474       DBusCondVar **cp;
 475
 476       cp = (DBusCondVar **)link->data;
 477       _dbus_assert (*cp == _DBUS_DUMMY_CONDVAR);
 478
 479       *cp = _dbus_condvar_new ();
 480       if (*cp == NULL)
 481         goto fail_condvar;
 482
 483       link = _dbus_list_get_next_link (&uninitialized_condvar_list, link);
 484     }
 485
 486   _dbus_list_clear (&uninitialized_rmutex_list);
 487   _dbus_list_clear (&uninitialized_cmutex_list);
 488   _dbus_list_clear (&uninitialized_condvar_list);
 489
 490   if (!_dbus_register_shutdown_func (shutdown_uninitialized_locks,
 491                                      NULL))
 492     goto fail_condvar;
 493
 494   return TRUE;
 495
 496  fail_condvar:
 497   link = uninitialized_condvar_list;
 498   while (link != NULL)
 499     {
 500       DBusCondVar **cp;
 501
 502       cp = (DBusCondVar **)link->data;
 503
 504       if (*cp != _DBUS_DUMMY_CONDVAR)
 505         _dbus_condvar_free (*cp);
 506       else
 507         break;
 508
 509       *cp = _DBUS_DUMMY_CONDVAR;
 510
 511       link = _dbus_list_get_next_link (&uninitialized_condvar_list, link);
 512     }
 513
 514  fail_mutex:
 515   link = uninitialized_rmutex_list;
 516   while (link != NULL)
 517     {
 518       DBusMutex **mp;
 519
 520       mp = link->data;
 521
 522       if (*mp != _DBUS_DUMMY_MUTEX)
 523         _dbus_mutex_free (*mp, thread_functions.recursive_mutex_free);
 524       else
 525         break;
 526
 527       *mp = _DBUS_DUMMY_MUTEX;
 528
 529       link = _dbus_list_get_next_link (&uninitialized_rmutex_list, link);
 530     }
 531
 532   link = uninitialized_cmutex_list;
 533   while (link != NULL)
 534     {
 535       DBusMutex **mp;
 536
 537       mp = link->data;
 538
 539       if (*mp != _DBUS_DUMMY_MUTEX)
 540         _dbus_mutex_free (*mp, thread_functions.mutex_free);
 541       else
 542         break;
 543
 544       *mp = _DBUS_DUMMY_MUTEX;
 545
 546       link = _dbus_list_get_next_link (&uninitialized_cmutex_list, link);
 547     }
 548
 549   return FALSE;
 550 }
 551
 552 static dbus_bool_t
 553 init_locks (void)
 554 {
 555   int i;
 556   DBusRMutex ***dynamic_global_locks;
 557   DBusRMutex **global_locks[] = {
 558 #define LOCK_ADDR(name) (& _dbus_lock_##name)
 559     LOCK_ADDR (win_fds),
 560     LOCK_ADDR (sid_atom_cache),
 561     LOCK_ADDR (list),
 562     LOCK_ADDR (connection_slots),
 563     LOCK_ADDR (pending_call_slots),
 564     LOCK_ADDR (server_slots),
 565     LOCK_ADDR (message_slots),
 566 #if !DBUS_USE_SYNC
 567     LOCK_ADDR (atomic),
 568 #endif
 569     LOCK_ADDR (bus),
 570     LOCK_ADDR (bus_datas),
 571     LOCK_ADDR (shutdown_funcs),
 572     LOCK_ADDR (system_users),
 573     LOCK_ADDR (message_cache),
 574     LOCK_ADDR (shared_connections),
 575     LOCK_ADDR (machine_uuid)
 576 #undef LOCK_ADDR
 577   };
 578
 579   _dbus_assert (_DBUS_N_ELEMENTS (global_locks) ==
 580                 _DBUS_N_GLOBAL_LOCKS);
 581
 582   i = 0;
 583
 584   dynamic_global_locks = dbus_new (DBusRMutex**, _DBUS_N_GLOBAL_LOCKS);
 585   if (dynamic_global_locks == NULL)
 586     goto failed;
 587
 588   while (i < _DBUS_N_ELEMENTS (global_locks))
 589     {
 590       *global_locks[i] = (DBusRMutex *) _dbus_mutex_new (thread_functions.recursive_mutex_new);
 591
 592       if (*global_locks[i] == NULL)
 593         goto failed;
 594
 595       dynamic_global_locks[i] = global_locks[i];
 596
 597       ++i;
 598     }
 599
 600   if (!_dbus_register_shutdown_func (shutdown_global_locks,
 601                                      dynamic_global_locks))
 602     goto failed;
 603
 604   if (!init_uninitialized_locks ())
 605     goto failed;
 606
 607   return TRUE;
 608
 609  failed:
 610   dbus_free (dynamic_global_locks);
 611
 612   for (i = i - 1; i >= 0; i--)
 613     {
 614       _dbus_mutex_free ((DBusMutex *) *global_locks[i],
 615                         thread_functions.recursive_mutex_free);
 616       *global_locks[i] = NULL;
 617     }
 618   return FALSE;
 619 }
 620
 621 /** @} */ /* end of internals */
 622
 623 /**
 624  * @defgroup DBusThreads Thread functions
 625  * @ingroup  DBus
 626  * @brief dbus_threads_init() and dbus_threads_init_default()
 627  *
 628  * Functions and macros related to threads and thread locks.
 629  *
 630  * If threads are initialized, the D-Bus library has locks on all
 631  * global data structures.  In addition, each #DBusConnection has a
 632  * lock, so only one thread at a time can touch the connection.  (See
 633  * @ref DBusConnection for more on connection locking.)
 634  *
 635  * Most other objects, however, do not have locks - they can only be
 636  * used from a single thread at a time, unless you lock them yourself.
 637  * For example, a #DBusMessage can't be modified from two threads
 638  * at once.
 639  *
 640  * @{
 641  */
 642
 643 /**
 644  *
 645  * Initializes threads. If this function is not called, the D-Bus
 646  * library will not lock any data structures.  If it is called, D-Bus
 647  * will do locking, at some cost in efficiency. Note that this
 648  * function must be called BEFORE the second thread is started.
 649  *
 650  * Almost always, you should use dbus_threads_init_default() instead.
 651  * The raw dbus_threads_init() is only useful if you require a
 652  * particular thread implementation for some reason.
 653  *
 654  * A possible reason to use dbus_threads_init() rather than
 655  * dbus_threads_init_default() is to insert debugging checks or print
 656  * statements.
 657  *
 658  * dbus_threads_init() may be called more than once.  The first one
 659  * wins and subsequent calls are ignored. (Unless you use
 660  * dbus_shutdown() to reset libdbus, which will let you re-init
 661  * threads.)
 662  *
 663  * Either recursive or nonrecursive mutex functions must be specified,
 664  * but not both. New code should provide only the recursive functions
 665  * - specifying the nonrecursive ones is deprecated.
 666  *
 667  * Because this function effectively sets global state, all code
 668  * running in a given application must agree on the thread
 669  * implementation. Most code won't care which thread implementation is
 670  * used, so there's no problem. However, usually libraries should not
 671  * call dbus_threads_init() or dbus_threads_init_default(), instead
 672  * leaving this policy choice to applications.
 673  *
 674  * The exception is for application frameworks (GLib, Qt, etc.)  and
 675  * D-Bus bindings based on application frameworks. These frameworks
 676  * define a cross-platform thread abstraction and can assume
 677  * applications using the framework are OK with using that thread
 678  * abstraction.
 679  *
 680  * However, even these app frameworks may find it easier to simply call
 681  * dbus_threads_init_default(), and there's no reason they shouldn't.
 682  *
 683  * @param functions functions for using threads
 684  * @returns #TRUE on success, #FALSE if no memory
 685  */
 686 dbus_bool_t
 687 dbus_threads_init (const DBusThreadFunctions *functions)
 688 {
 689   dbus_bool_t mutex_set;
 690   dbus_bool_t recursive_mutex_set;
 691
 692   _dbus_assert (functions != NULL);
 693
 694   /* these base functions are required. Future additions to
 695    * DBusThreadFunctions may be optional.
 696    */
 697   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK);
 698   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK);
 699   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK);
 700   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK);
 701   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK);
 702   _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK);
 703   _dbus_assert (functions->condvar_new != NULL);
 704   _dbus_assert (functions->condvar_free != NULL);
 705   _dbus_assert (functions->condvar_wait != NULL);
 706   _dbus_assert (functions->condvar_wait_timeout != NULL);
 707   _dbus_assert (functions->condvar_wake_one != NULL);
 708   _dbus_assert (functions->condvar_wake_all != NULL);
 709
 710   /* Either the mutex function set or recursive mutex set needs
 711    * to be available but not both
 712    */
 713   mutex_set = (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK) &&
 714               (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK) &&
 715               (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK) &&
 716               (functions->mask & DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK) &&
 717                functions->mutex_new &&
 718                functions->mutex_free &&
 719                functions->mutex_lock &&
 720                functions->mutex_unlock;
 721
 722   recursive_mutex_set =
 723               (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_NEW_MASK) &&
 724               (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_FREE_MASK) &&
 725               (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_LOCK_MASK) &&
 726               (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_UNLOCK_MASK) &&
 727                 functions->recursive_mutex_new &&
 728                 functions->recursive_mutex_free &&
 729                 functions->recursive_mutex_lock &&
 730                 functions->recursive_mutex_unlock;
 731
 732   if (!(mutex_set || recursive_mutex_set))
 733     _dbus_assert_not_reached ("Either the nonrecusrive or recursive mutex "
 734                               "functions sets should be passed into "
 735                               "dbus_threads_init. Neither sets were passed.");
 736
 737   if (mutex_set && recursive_mutex_set)
 738     _dbus_assert_not_reached ("Either the nonrecusrive or recursive mutex "
 739                               "functions sets should be passed into "
 740                               "dbus_threads_init. Both sets were passed. "
 741                               "You most likely just want to set the recursive "
 742                               "mutex functions to avoid deadlocks in D-Bus.");
 743
 744   /* Check that all bits in the mask actually are valid mask bits.
 745    * ensures people won't write code that breaks when we add
 746    * new bits.
 747    */
 748   _dbus_assert ((functions->mask & ~DBUS_THREAD_FUNCTIONS_ALL_MASK) == 0);
 749
 750   if (thread_init_generation != _dbus_current_generation)
 751     thread_functions.mask = 0; /* allow re-init in new generation */
 752
 753   /* Silently allow multiple init
 754    * First init wins and D-Bus will always use its threading system
 755    */
 756   if (thread_functions.mask != 0)
 757     return TRUE;
 758
 759   thread_functions.mutex_new = functions->mutex_new;
 760   thread_functions.mutex_free = functions->mutex_free;
 761   thread_functions.mutex_lock = functions->mutex_lock;
 762   thread_functions.mutex_unlock = functions->mutex_unlock;
 763
 764   thread_functions.condvar_new = functions->condvar_new;
 765   thread_functions.condvar_free = functions->condvar_free;
 766   thread_functions.condvar_wait = functions->condvar_wait;
 767   thread_functions.condvar_wait_timeout = functions->condvar_wait_timeout;
 768   thread_functions.condvar_wake_one = functions->condvar_wake_one;
 769   thread_functions.condvar_wake_all = functions->condvar_wake_all;
 770
 771   if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_NEW_MASK)
 772     thread_functions.recursive_mutex_new = functions->recursive_mutex_new;
 773
 774   if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_FREE_MASK)
 775     thread_functions.recursive_mutex_free = functions->recursive_mutex_free;
 776
 777   if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_LOCK_MASK)
 778     thread_functions.recursive_mutex_lock = functions->recursive_mutex_lock;
 779
 780   if (functions->mask & DBUS_THREAD_FUNCTIONS_RECURSIVE_MUTEX_UNLOCK_MASK)
 781     thread_functions.recursive_mutex_unlock = functions->recursive_mutex_unlock;
 782
 783   thread_functions.mask = functions->mask;
 784
 785   if (!init_locks ())
 786     return FALSE;
 787
 788   thread_init_generation = _dbus_current_generation;
 789
 790   return TRUE;
 791 }
 792
 793
 794
 795 /* Default thread implemenation */
 796
 797 /**
 798  *
 799  * Calls dbus_threads_init() with a default set of
 800  * #DBusThreadFunctions appropriate for the platform.
 801  *
 802  * Most applications should use this rather than dbus_threads_init().
 803  *
 804  * It's safe to call dbus_threads_init_default() as many times as you
 805  * want, but only the first time will have an effect.
 806  *
 807  * dbus_shutdown() reverses the effects of this function when it
 808  * resets all global state in libdbus.
 809  *
 810  * @returns #TRUE on success, #FALSE if not enough memory
 811  */
 812 dbus_bool_t
 813 dbus_threads_init_default (void)
 814 {
 815   return _dbus_threads_init_platform_specific ();
 816 }
 817
 818
 819 /** @} */
 820
 821 #ifdef DBUS_BUILD_TESTS
 822 /** Fake mutex used for debugging */
 823 typedef struct DBusFakeMutex DBusFakeMutex;
 824 /** Fake mutex used for debugging */
 825 struct DBusFakeMutex
 826 {
 827   dbus_bool_t locked; /**< Mutex is "locked" */
 828 };
 829
 830 static DBusMutex *  dbus_fake_mutex_new            (void);
 831 static void         dbus_fake_mutex_free           (DBusMutex   *mutex);
 832 static dbus_bool_t  dbus_fake_mutex_lock           (DBusMutex   *mutex);
 833 static dbus_bool_t  dbus_fake_mutex_unlock         (DBusMutex   *mutex);
 834 static DBusCondVar* dbus_fake_condvar_new          (void);
 835 static void         dbus_fake_condvar_free         (DBusCondVar *cond);
 836 static void         dbus_fake_condvar_wait         (DBusCondVar *cond,
 837                                                     DBusMutex   *mutex);
 838 static dbus_bool_t  dbus_fake_condvar_wait_timeout (DBusCondVar *cond,
 839                                                     DBusMutex   *mutex,
 840                                                     int          timeout_msec);
 841 static void         dbus_fake_condvar_wake_one     (DBusCondVar *cond);
 842 static void         dbus_fake_condvar_wake_all     (DBusCondVar *cond);
 843
 844
 845 static const DBusThreadFunctions fake_functions =
 846 {
 847   DBUS_THREAD_FUNCTIONS_MUTEX_NEW_MASK |
 848   DBUS_THREAD_FUNCTIONS_MUTEX_FREE_MASK |
 849   DBUS_THREAD_FUNCTIONS_MUTEX_LOCK_MASK |
 850   DBUS_THREAD_FUNCTIONS_MUTEX_UNLOCK_MASK |
 851   DBUS_THREAD_FUNCTIONS_CONDVAR_NEW_MASK |
 852   DBUS_THREAD_FUNCTIONS_CONDVAR_FREE_MASK |
 853   DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_MASK |
 854   DBUS_THREAD_FUNCTIONS_CONDVAR_WAIT_TIMEOUT_MASK |
 855   DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ONE_MASK|
 856   DBUS_THREAD_FUNCTIONS_CONDVAR_WAKE_ALL_MASK,
 857   dbus_fake_mutex_new,
 858   dbus_fake_mutex_free,
 859   dbus_fake_mutex_lock,
 860   dbus_fake_mutex_unlock,
 861   dbus_fake_condvar_new,
 862   dbus_fake_condvar_free,
 863   dbus_fake_condvar_wait,
 864   dbus_fake_condvar_wait_timeout,
 865   dbus_fake_condvar_wake_one,
 866   dbus_fake_condvar_wake_all
 867 };
 868
 869 static DBusMutex *
 870 dbus_fake_mutex_new (void)
 871 {
 872   DBusFakeMutex *mutex;
 873
 874   mutex = dbus_new0 (DBusFakeMutex, 1);
 875
 876   return (DBusMutex *)mutex;
 877 }
 878
 879 static void
 880 dbus_fake_mutex_free (DBusMutex *mutex)
 881 {
 882   DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
 883
 884   _dbus_assert (!fake->locked);
 885
 886   dbus_free (fake);
 887 }
 888
 889 static dbus_bool_t
 890 dbus_fake_mutex_lock (DBusMutex *mutex)
 891 {
 892   DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
 893
 894   _dbus_assert (!fake->locked);
 895
 896   fake->locked = TRUE;
 897
 898   return TRUE;
 899 }
 900
 901 static dbus_bool_t
 902 dbus_fake_mutex_unlock (DBusMutex *mutex)
 903 {
 904   DBusFakeMutex *fake = (DBusFakeMutex*) mutex;
 905
 906   _dbus_assert (fake->locked);
 907
 908   fake->locked = FALSE;
 909
 910   return TRUE;
 911 }
 912
 913 static DBusCondVar*
 914 dbus_fake_condvar_new (void)
 915 {
 916   return (DBusCondVar*) _dbus_strdup ("FakeCondvar");
 917 }
 918
 919 static void
 920 dbus_fake_condvar_free (DBusCondVar *cond)
 921 {
 922   dbus_free (cond);
 923 }
 924
 925 static void
 926 dbus_fake_condvar_wait (DBusCondVar *cond,
 927                         DBusMutex   *mutex)
 928 {
 929
 930 }
 931
 932 static dbus_bool_t
 933 dbus_fake_condvar_wait_timeout (DBusCondVar *cond,
 934                                 DBusMutex   *mutex,
 935                                 int         timeout_msec)
 936 {
 937   return TRUE;
 938 }
 939
 940 static void
 941 dbus_fake_condvar_wake_one (DBusCondVar *cond)
 942 {
 943
 944 }
 945
 946 static void
 947 dbus_fake_condvar_wake_all (DBusCondVar *cond)
 948 {
 949
 950 }
 951
 952 dbus_bool_t
 953 _dbus_threads_init_debug (void)
 954 {
 955 #ifdef DBUS_WIN
 956   return _dbus_threads_init_platform_specific();
 957 #else
 958   return dbus_threads_init (&fake_functions);
 959 #endif
 960 }
 961
 962 #endif /* DBUS_BUILD_TESTS */