From 83e48d8ac1fee98059e2305d8909dca26190bddc Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 17 Nov 2020 10:15:15 +0000 Subject: [PATCH 29/29] docs: Document not to use `volatile` qualifiers Signed-off-by: Philip Withnall Fixes: #600 Upstream-Status: Backport [https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1719] --- gio/gdbusconnection.c | 12 ++++++++--- gio/gdbuserror.c | 3 +++ glib/gatomic.c | 48 +++++++++++++++++++++++++++++++++++++++++++ glib/gthread.c | 6 ++++++ 4 files changed, 66 insertions(+), 3 deletions(-) diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c index 91c365e80..65939a4d2 100644 --- a/gio/gdbusconnection.c +++ b/gio/gdbusconnection.c @@ -1708,7 +1708,9 @@ g_dbus_connection_send_message_unlocked (GDBusConnection *connection, * will be assigned by @connection and set on @message via * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the * serial number used will be written to this location prior to - * submitting the message to the underlying transport. + * submitting the message to the underlying transport. While it has a `volatile` + * qualifier, this is a historical artifact and the argument passed to it should + * not be `volatile`. * * If @connection is closed then the operation will fail with * %G_IO_ERROR_CLOSED. If @message is not well-formed, @@ -1979,7 +1981,9 @@ g_dbus_connection_send_message_with_reply_unlocked (GDBusConnection *connect * will be assigned by @connection and set on @message via * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the * serial number used will be written to this location prior to - * submitting the message to the underlying transport. + * submitting the message to the underlying transport. While it has a `volatile` + * qualifier, this is a historical artifact and the argument passed to it should + * not be `volatile`. * * If @connection is closed then the operation will fail with * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will @@ -2105,7 +2109,9 @@ send_message_with_reply_sync_cb (GDBusConnection *connection, * will be assigned by @connection and set on @message via * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the * serial number used will be written to this location prior to - * submitting the message to the underlying transport. + * submitting the message to the underlying transport. While it has a `volatile` + * qualifier, this is a historical artifact and the argument passed to it should + * not be `volatile`. * * If @connection is closed then the operation will fail with * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will diff --git a/gio/gdbuserror.c b/gio/gdbuserror.c index b03a33f27..4ad97bb6e 100644 --- a/gio/gdbuserror.c +++ b/gio/gdbuserror.c @@ -177,6 +177,9 @@ g_dbus_error_quark (void) * * Helper function for associating a #GError error domain with D-Bus error names. * + * While @quark_volatile has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. + * * Since: 2.26 */ void diff --git a/glib/gatomic.c b/glib/gatomic.c index 67f5ba6b4..0bc67aa35 100644 --- a/glib/gatomic.c +++ b/glib/gatomic.c @@ -105,6 +105,9 @@ * This call acts as a full compiler and hardware * memory barrier (before the get). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of the integer * * Since: 2.4 @@ -125,6 +128,9 @@ gint * This call acts as a full compiler and hardware * memory barrier (after the set). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.4 */ void @@ -144,6 +150,9 @@ void * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.4 **/ void @@ -163,6 +172,9 @@ void * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the resultant value is zero * * Since: 2.4 @@ -189,6 +201,9 @@ gboolean * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the exchange took place * * Since: 2.4 @@ -216,6 +231,9 @@ gboolean * Before version 2.30, this function did not return a value * (but g_atomic_int_exchange_and_add() did, and had the same meaning). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the add, signed * * Since: 2.4 @@ -240,6 +258,9 @@ gint * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic &= val; return tmp; }`. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * * Since: 2.30 @@ -264,6 +285,9 @@ guint * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * * Since: 2.30 @@ -288,6 +312,9 @@ guint * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * * Since: 2.30 @@ -309,6 +336,9 @@ guint * This call acts as a full compiler and hardware * memory barrier (before the get). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of the pointer * * Since: 2.4 @@ -329,6 +359,9 @@ gpointer * This call acts as a full compiler and hardware * memory barrier (after the set). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.4 **/ void @@ -354,6 +387,9 @@ void * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the exchange took place * * Since: 2.4 @@ -379,6 +415,9 @@ gboolean * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the add, signed * * Since: 2.30 @@ -403,6 +442,9 @@ gssize * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * * Since: 2.30 @@ -427,6 +469,9 @@ gsize * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * * Since: 2.30 @@ -451,6 +496,9 @@ gsize * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * * Since: 2.30 diff --git a/glib/gthread.c b/glib/gthread.c index 612a9739f..29216d7fd 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -686,6 +686,9 @@ g_once_impl (GOnce *once, * // use initialization_value here * ]| * + * While @location has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the initialization section should be entered, * %FALSE and blocks otherwise * @@ -725,6 +728,9 @@ gboolean * releases concurrent threads blocking in g_once_init_enter() on this * initialization variable. * + * While @location has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.14 */ void -- 2.30.1