-/* -*- mode: C; c-file-style: "gnu" -*- */
-/* dbus-threads.h D-BUS threads handling
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
+/* dbus-threads.h D-Bus threads handling
*
- * Copyright (C) 2002 Red Hat Inc.
+ * Copyright (C) 2002, 2003, 2006 Red Hat Inc.
*
- * Licensed under the Academic Free License version 1.2
+ * Licensed under the Academic Free License version 2.1
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*
*/
+#include <config.h>
#include "dbus-threads.h"
#include "dbus-internals.h"
+#include "dbus-threads-internal.h"
+#include "dbus-list.h"
-static DBusThreadFunctions thread_functions =
-{
- 0,
- NULL, NULL, NULL, NULL,
-
- NULL, NULL, NULL, NULL,
- NULL, NULL, NULL, NULL
-};
-
-static DBusMutex *static_mutex_init_lock = NULL;
-
-/** This is used for the no-op default mutex pointer, just to be distinct from #NULL */
-#define _DBUS_DUMMY_MUTEX ((void*)0xABCDEF)
+static int thread_init_generation = 0;
/**
- * @defgroup DBusThreads Thread functions
- * @ingroup DBus
- * @brief dbus_threads_init(), dbus_mutex_lock(), etc.
+ * @defgroup DBusThreadsInternals Thread functions
+ * @ingroup DBusInternals
+ * @brief _dbus_rmutex_lock(), etc.
*
* Functions and macros related to threads and thread locks.
*
*/
/**
- * Creates a new mutex using the function supplied to dbus_threads_init(),
+ * Creates a new mutex
* or creates a no-op mutex if threads are not initialized.
* May return #NULL even if threads are initialized, indicating
* out-of-memory.
*
- * @returns new mutex or #NULL
+ * If possible, the mutex returned by this function is recursive, to
+ * avoid deadlocks. However, that cannot be relied on.
+ *
+ * @param location_p the location of the new mutex, can return #NULL on OOM
*/
-DBusMutex*
-dbus_mutex_new (void)
+void
+_dbus_rmutex_new_at_location (DBusRMutex **location_p)
{
- if (thread_functions.mutex_new)
- return (* thread_functions.mutex_new) ();
- else
- return _DBUS_DUMMY_MUTEX;
+ _dbus_assert (location_p != NULL);
+
+ if (!dbus_threads_init_default ())
+ {
+ *location_p = NULL;
+ return;
+ }
+
+ *location_p = _dbus_platform_rmutex_new ();
}
/**
- * Frees a mutex created with dbus_mutex_new(); does
- * nothing if passed a #NULL pointer.
+ * Creates a new mutex
+ * or creates a no-op mutex if threads are not initialized.
+ * May return #NULL even if threads are initialized, indicating
+ * out-of-memory.
+ *
+ * The returned mutex is suitable for use with condition variables.
+ *
+ * @param location_p the location of the new mutex, can return #NULL on OOM
*/
void
-dbus_mutex_free (DBusMutex *mutex)
+_dbus_cmutex_new_at_location (DBusCMutex **location_p)
{
- if (mutex && thread_functions.mutex_free)
- (* thread_functions.mutex_free) (mutex);
+ _dbus_assert (location_p != NULL);
+
+ if (!dbus_threads_init_default ())
+ {
+ *location_p = NULL;
+ return;
+ }
+
+ *location_p = _dbus_platform_cmutex_new ();
+}
+
+/**
+ * Frees a DBusRMutex; does nothing if passed a #NULL pointer.
+ */
+void
+_dbus_rmutex_free_at_location (DBusRMutex **location_p)
+{
+ if (location_p == NULL)
+ return;
+
+ if (*location_p != NULL)
+ _dbus_platform_rmutex_free (*location_p);
+}
+
+/**
+ * Frees a DBusCMutex; does nothing if passed a #NULL pointer.
+ */
+void
+_dbus_cmutex_free_at_location (DBusCMutex **location_p)
+{
+ if (location_p == NULL)
+ return;
+
+ if (*location_p != NULL)
+ _dbus_platform_cmutex_free (*location_p);
+}
+
+/**
+ * Locks a mutex. Does nothing if passed a #NULL pointer.
+ * Locks may be recursive if threading implementation initialized
+ * recursive locks.
+ */
+void
+_dbus_rmutex_lock (DBusRMutex *mutex)
+{
+ if (mutex == NULL)
+ return;
+
+ _dbus_platform_rmutex_lock (mutex);
}
/**
* Locks a mutex. Does nothing if passed a #NULL pointer.
- * Locks are not recursive.
+ * Locks may be recursive if threading implementation initialized
+ * recursive locks.
+ */
+void
+_dbus_cmutex_lock (DBusCMutex *mutex)
+{
+ if (mutex == NULL)
+ return;
+
+ _dbus_platform_cmutex_lock (mutex);
+}
+
+/**
+ * Unlocks a mutex. Does nothing if passed a #NULL pointer.
*
* @returns #TRUE on success
*/
-dbus_bool_t
-dbus_mutex_lock (DBusMutex *mutex)
+void
+_dbus_rmutex_unlock (DBusRMutex *mutex)
{
- if (mutex && thread_functions.mutex_lock)
- return (* thread_functions.mutex_lock) (mutex);
- else
- return TRUE;
+ if (mutex == NULL)
+ return;
+
+ _dbus_platform_rmutex_unlock (mutex);
}
/**
*
* @returns #TRUE on success
*/
-dbus_bool_t
-dbus_mutex_unlock (DBusMutex *mutex)
+void
+_dbus_cmutex_unlock (DBusCMutex *mutex)
{
- if (mutex && thread_functions.mutex_unlock)
- return (* thread_functions.mutex_unlock) (mutex);
- else
- return TRUE;
+ if (mutex == NULL)
+ return;
+
+ _dbus_platform_cmutex_unlock (mutex);
}
/**
- * Initializes threads. If this function is not called,
- * the D-BUS library will not lock any data structures.
- * If it is called, D-BUS will do locking, at some cost
- * in efficiency. Note that this function must be called
- * BEFORE using any other D-BUS functions.
+ * Creates a new condition variable using the function supplied
+ * to dbus_threads_init(), or creates a no-op condition variable
+ * if threads are not initialized. May return #NULL even if
+ * threads are initialized, indicating out-of-memory.
*
- * @todo right now this function can only be called once,
- * maybe we should instead silently ignore multiple calls.
+ * @returns new mutex or #NULL
+ */
+DBusCondVar *
+_dbus_condvar_new (void)
+{
+ if (!dbus_threads_init_default ())
+ return NULL;
+
+ return _dbus_platform_condvar_new ();
+}
+
+
+/**
+ * This does the same thing as _dbus_condvar_new. It however
+ * gives another level of indirection by allocating a pointer
+ * to point to the condvar location; this used to be useful.
*
- * @param functions functions for using threads
- * @returns #TRUE on success, #FALSE if no memory
+ * @returns the location of a new condvar or #NULL on OOM
+ */
+
+void
+_dbus_condvar_new_at_location (DBusCondVar **location_p)
+{
+ _dbus_assert (location_p != NULL);
+
+ *location_p = _dbus_condvar_new();
+}
+
+
+/**
+ * Frees a conditional variable created with dbus_condvar_new(); does
+ * nothing if passed a #NULL pointer.
+ */
+void
+_dbus_condvar_free (DBusCondVar *cond)
+{
+ if (cond == NULL)
+ return;
+
+ _dbus_platform_condvar_free (cond);
+}
+
+/**
+ * Frees a condition variable; does nothing if passed a #NULL pointer.
+ */
+void
+_dbus_condvar_free_at_location (DBusCondVar **location_p)
+{
+ if (location_p == NULL)
+ return;
+
+ if (*location_p != NULL)
+ _dbus_platform_condvar_free (*location_p);
+}
+
+/**
+ * Atomically unlocks the mutex and waits for the conditions
+ * variable to be signalled. Locks the mutex again before
+ * returning.
+ * Does nothing if passed a #NULL pointer.
+ */
+void
+_dbus_condvar_wait (DBusCondVar *cond,
+ DBusCMutex *mutex)
+{
+ if (cond == NULL || mutex == NULL)
+ return;
+
+ _dbus_platform_condvar_wait (cond, mutex);
+}
+
+/**
+ * Atomically unlocks the mutex and waits for the conditions variable
+ * to be signalled, or for a timeout. Locks the mutex again before
+ * returning. Does nothing if passed a #NULL pointer. Return value
+ * is #FALSE if we timed out, #TRUE otherwise.
+ *
+ * @param cond the condition variable
+ * @param mutex the mutex
+ * @param timeout_milliseconds the maximum time to wait
+ * @returns #FALSE if the timeout occurred, #TRUE if not
*/
dbus_bool_t
-dbus_threads_init (const DBusThreadFunctions *functions)
+_dbus_condvar_wait_timeout (DBusCondVar *cond,
+ DBusCMutex *mutex,
+ int timeout_milliseconds)
{
- _dbus_assert (functions != NULL);
-
- /* these base functions are required. Future additions to
- * DBusThreadFunctions may be optional.
- */
- _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_NEW_MASK);
- _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_FREE_MASK);
- _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_LOCK_MASK);
- _dbus_assert (functions->mask & DBUS_THREAD_FUNCTIONS_UNLOCK_MASK);
- _dbus_assert (functions->mutex_new != NULL);
- _dbus_assert (functions->mutex_free != NULL);
- _dbus_assert (functions->mutex_lock != NULL);
- _dbus_assert (functions->mutex_unlock != NULL);
-
- /* Check that all bits in the mask actually are valid mask bits.
- * ensures people won't write code that breaks when we add
- * new bits.
- */
- _dbus_assert ((functions->mask & ~DBUS_THREAD_FUNCTIONS_ALL_MASK) == 0);
-
- if (thread_functions.mask != 0)
+ if (cond == NULL || mutex == NULL)
+ return TRUE;
+
+ return _dbus_platform_condvar_wait_timeout (cond, mutex,
+ timeout_milliseconds);
+}
+
+/**
+ * If there are threads waiting on the condition variable, wake
+ * up exactly one.
+ * Does nothing if passed a #NULL pointer.
+ */
+void
+_dbus_condvar_wake_one (DBusCondVar *cond)
+{
+ if (cond == NULL)
+ return;
+
+ _dbus_platform_condvar_wake_one (cond);
+}
+
+static DBusRMutex *global_locks[_DBUS_N_GLOBAL_LOCKS] = { NULL };
+
+static void
+shutdown_global_locks (void *nil)
+{
+ int i;
+
+ for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
{
- _dbus_warn ("dbus_threads_init() may only be called one time\n");
- return FALSE;
+ _dbus_assert (global_locks[i] != NULL);
+ _dbus_platform_rmutex_free (global_locks[i]);
+ global_locks[i] = NULL;
}
-
- thread_functions.mutex_new = functions->mutex_new;
- thread_functions.mutex_free = functions->mutex_free;
- thread_functions.mutex_lock = functions->mutex_lock;
- thread_functions.mutex_unlock = functions->mutex_unlock;
-
- thread_functions.mask = functions->mask;
+}
- static_mutex_init_lock = dbus_mutex_new ();
+static dbus_bool_t
+init_global_locks (void)
+{
+ int i;
+ dbus_bool_t ok;
- if (static_mutex_init_lock == NULL)
+ for (i = 0; i < _DBUS_N_GLOBAL_LOCKS; i++)
{
- thread_functions.mask = 0;
- return FALSE;
+ _dbus_assert (global_locks[i] == NULL);
+
+ global_locks[i] = _dbus_platform_rmutex_new ();
+
+ if (global_locks[i] == NULL)
+ goto failed;
}
+ _dbus_platform_rmutex_lock (global_locks[_DBUS_LOCK_shutdown_funcs]);
+ ok = _dbus_register_shutdown_func_unlocked (shutdown_global_locks, NULL);
+ _dbus_platform_rmutex_unlock (global_locks[_DBUS_LOCK_shutdown_funcs]);
+
+ if (!ok)
+ goto failed;
+
return TRUE;
+
+ failed:
+ for (i = i - 1; i >= 0; i--)
+ {
+ _dbus_platform_rmutex_free (global_locks[i]);
+ global_locks[i] = NULL;
+ }
+
+ return FALSE;
}
-/** Accesses the field of DBusStaticMutex that
- * stores the DBusMutex used to implement.
- */
-#define _DBUS_STATIC_MUTEX_IMPL(mutex) ((mutex)->pad1)
+dbus_bool_t
+_dbus_lock (DBusGlobalLock lock)
+{
+ _dbus_assert (lock >= 0);
+ _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
+
+ if (thread_init_generation != _dbus_current_generation &&
+ !dbus_threads_init_default ())
+ return FALSE;
+
+ _dbus_platform_rmutex_lock (global_locks[lock]);
+ return TRUE;
+}
+
+void
+_dbus_unlock (DBusGlobalLock lock)
+{
+ _dbus_assert (lock >= 0);
+ _dbus_assert (lock < _DBUS_N_GLOBAL_LOCKS);
+
+ _dbus_platform_rmutex_unlock (global_locks[lock]);
+}
+
+/** @} */ /* end of internals */
/**
- * Lock a static mutex
+ * @defgroup DBusThreads Thread functions
+ * @ingroup DBus
+ * @brief dbus_threads_init() and dbus_threads_init_default()
+ *
+ * Functions and macros related to threads and thread locks.
+ *
+ * If threads are initialized, the D-Bus library has locks on all
+ * global data structures. In addition, each #DBusConnection has a
+ * lock, so only one thread at a time can touch the connection. (See
+ * @ref DBusConnection for more on connection locking.)
*
- * @todo currently broken on some platforms due to
- * non-workingness of "double checked locking"
- * see http://bugzilla.gnome.org/show_bug.cgi?id=69668
- * and http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html
- * for example.
+ * Most other objects, however, do not have locks - they can only be
+ * used from a single thread at a time, unless you lock them yourself.
+ * For example, a #DBusMessage can't be modified from two threads
+ * at once.
*
- * @param mutex the mutex to lock
- * @returns #TRUE on success
+ * @{
+ */
+
+/**
+ * Initializes threads, like dbus_threads_init_default().
+ * This version previously allowed user-specified threading
+ * primitives, but since D-Bus 1.6 it ignores them and behaves
+ * exactly like dbus_threads_init_default().
+ *
+ * @param functions ignored, formerly functions for using threads
+ * @returns #TRUE on success, #FALSE if no memory
*/
dbus_bool_t
-dbus_static_mutex_lock (DBusStaticMutex *mutex)
-{
- if (_DBUS_STATIC_MUTEX_IMPL (mutex))
- return dbus_mutex_lock (_DBUS_STATIC_MUTEX_IMPL (mutex));
+dbus_threads_init (const DBusThreadFunctions *functions)
+{
+ _dbus_threads_lock_platform_specific ();
- if (!dbus_mutex_lock (static_mutex_init_lock))
- return FALSE;
+ if (thread_init_generation == _dbus_current_generation)
+ {
+ _dbus_threads_unlock_platform_specific ();
+ return TRUE;
+ }
+
+ if (!_dbus_threads_init_platform_specific() ||
+ !init_global_locks ())
+ {
+ _dbus_threads_unlock_platform_specific ();
+ return FALSE;
+ }
- if (_DBUS_STATIC_MUTEX_IMPL (mutex) == NULL)
- _DBUS_STATIC_MUTEX_IMPL (mutex) = dbus_mutex_new ();
-
- dbus_mutex_unlock (static_mutex_init_lock);
+ thread_init_generation = _dbus_current_generation;
- if (_DBUS_STATIC_MUTEX_IMPL (mutex))
- return dbus_mutex_lock (_DBUS_STATIC_MUTEX_IMPL (mutex));
- else
- return FALSE;
+ _dbus_threads_unlock_platform_specific ();
+ return TRUE;
}
+
+
+/* Default thread implemenation */
+
/**
- * Unlock a static mutex
- * @param mutex the mutex to lock
- * @returns #TRUE on success
+ * Initializes threads. If this function is not called, the D-Bus
+ * library will not lock any data structures. If it is called, D-Bus
+ * will do locking, at some cost in efficiency.
+ *
+ * Since D-Bus 1.7 it is safe to call this function from any thread,
+ * any number of times (but it must be called before any other
+ * libdbus API is used).
+ *
+ * In D-Bus 1.6 or older, this function must be called in the main thread
+ * before any other thread starts. As a result, it is not sufficient to
+ * call this function in a library or plugin, unless the library or plugin
+ * imposes a similar requirement on its callers.
+ *
+ * dbus_shutdown() reverses the effects of this function when it
+ * resets all global state in libdbus.
+ *
+ * @returns #TRUE on success, #FALSE if not enough memory
*/
dbus_bool_t
-dbus_static_mutex_unlock (DBusStaticMutex *mutex)
+dbus_threads_init_default (void)
{
- _dbus_assert (_DBUS_STATIC_MUTEX_IMPL (mutex) != NULL);
-
- return dbus_mutex_unlock (_DBUS_STATIC_MUTEX_IMPL (mutex));
+ return dbus_threads_init (NULL);
}
+
/** @} */
+
+#ifdef DBUS_ENABLE_EMBEDDED_TESTS
+
+dbus_bool_t
+_dbus_threads_init_debug (void)
+{
+ return dbus_threads_init (NULL);
+}
+
+#endif /* DBUS_ENABLE_EMBEDDED_TESTS */
projects / platform / upstream / dbus.git / blobdiff