| From 83e48d8ac1fee98059e2305d8909dca26190bddc Mon Sep 17 00:00:00 2001 |
| From: Philip Withnall <pwithnall@endlessos.org> |
| 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 <pwithnall@endlessos.org> |
| |
| 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 |
| |