Andrew Geissler | 95ac1b8 | 2021-03-31 14:34:31 -0500 | [diff] [blame] | 1 | From 83e48d8ac1fee98059e2305d8909dca26190bddc Mon Sep 17 00:00:00 2001 |
| 2 | From: Philip Withnall <pwithnall@endlessos.org> |
| 3 | Date: Tue, 17 Nov 2020 10:15:15 +0000 |
| 4 | Subject: [PATCH 29/29] docs: Document not to use `volatile` qualifiers |
| 5 | |
| 6 | Signed-off-by: Philip Withnall <pwithnall@endlessos.org> |
| 7 | |
| 8 | Fixes: #600 |
| 9 | Upstream-Status: Backport [https://gitlab.gnome.org/GNOME/glib/-/merge_requests/1719] |
| 10 | --- |
| 11 | gio/gdbusconnection.c | 12 ++++++++--- |
| 12 | gio/gdbuserror.c | 3 +++ |
| 13 | glib/gatomic.c | 48 +++++++++++++++++++++++++++++++++++++++++++ |
| 14 | glib/gthread.c | 6 ++++++ |
| 15 | 4 files changed, 66 insertions(+), 3 deletions(-) |
| 16 | |
| 17 | diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c |
| 18 | index 91c365e80..65939a4d2 100644 |
| 19 | --- a/gio/gdbusconnection.c |
| 20 | +++ b/gio/gdbusconnection.c |
| 21 | @@ -1708,7 +1708,9 @@ g_dbus_connection_send_message_unlocked (GDBusConnection *connection, |
| 22 | * will be assigned by @connection and set on @message via |
| 23 | * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the |
| 24 | * serial number used will be written to this location prior to |
| 25 | - * submitting the message to the underlying transport. |
| 26 | + * submitting the message to the underlying transport. While it has a `volatile` |
| 27 | + * qualifier, this is a historical artifact and the argument passed to it should |
| 28 | + * not be `volatile`. |
| 29 | * |
| 30 | * If @connection is closed then the operation will fail with |
| 31 | * %G_IO_ERROR_CLOSED. If @message is not well-formed, |
| 32 | @@ -1979,7 +1981,9 @@ g_dbus_connection_send_message_with_reply_unlocked (GDBusConnection *connect |
| 33 | * will be assigned by @connection and set on @message via |
| 34 | * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the |
| 35 | * serial number used will be written to this location prior to |
| 36 | - * submitting the message to the underlying transport. |
| 37 | + * submitting the message to the underlying transport. While it has a `volatile` |
| 38 | + * qualifier, this is a historical artifact and the argument passed to it should |
| 39 | + * not be `volatile`. |
| 40 | * |
| 41 | * If @connection is closed then the operation will fail with |
| 42 | * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will |
| 43 | @@ -2105,7 +2109,9 @@ send_message_with_reply_sync_cb (GDBusConnection *connection, |
| 44 | * will be assigned by @connection and set on @message via |
| 45 | * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the |
| 46 | * serial number used will be written to this location prior to |
| 47 | - * submitting the message to the underlying transport. |
| 48 | + * submitting the message to the underlying transport. While it has a `volatile` |
| 49 | + * qualifier, this is a historical artifact and the argument passed to it should |
| 50 | + * not be `volatile`. |
| 51 | * |
| 52 | * If @connection is closed then the operation will fail with |
| 53 | * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will |
| 54 | diff --git a/gio/gdbuserror.c b/gio/gdbuserror.c |
| 55 | index b03a33f27..4ad97bb6e 100644 |
| 56 | --- a/gio/gdbuserror.c |
| 57 | +++ b/gio/gdbuserror.c |
| 58 | @@ -177,6 +177,9 @@ g_dbus_error_quark (void) |
| 59 | * |
| 60 | * Helper function for associating a #GError error domain with D-Bus error names. |
| 61 | * |
| 62 | + * While @quark_volatile has a `volatile` qualifier, this is a historical |
| 63 | + * artifact and the argument passed to it should not be `volatile`. |
| 64 | + * |
| 65 | * Since: 2.26 |
| 66 | */ |
| 67 | void |
| 68 | diff --git a/glib/gatomic.c b/glib/gatomic.c |
| 69 | index 67f5ba6b4..0bc67aa35 100644 |
| 70 | --- a/glib/gatomic.c |
| 71 | +++ b/glib/gatomic.c |
| 72 | @@ -105,6 +105,9 @@ |
| 73 | * This call acts as a full compiler and hardware |
| 74 | * memory barrier (before the get). |
| 75 | * |
| 76 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 77 | + * the pointer passed to it should not be `volatile`. |
| 78 | + * |
| 79 | * Returns: the value of the integer |
| 80 | * |
| 81 | * Since: 2.4 |
| 82 | @@ -125,6 +128,9 @@ gint |
| 83 | * This call acts as a full compiler and hardware |
| 84 | * memory barrier (after the set). |
| 85 | * |
| 86 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 87 | + * the pointer passed to it should not be `volatile`. |
| 88 | + * |
| 89 | * Since: 2.4 |
| 90 | */ |
| 91 | void |
| 92 | @@ -144,6 +150,9 @@ void |
| 93 | * |
| 94 | * This call acts as a full compiler and hardware memory barrier. |
| 95 | * |
| 96 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 97 | + * the pointer passed to it should not be `volatile`. |
| 98 | + * |
| 99 | * Since: 2.4 |
| 100 | **/ |
| 101 | void |
| 102 | @@ -163,6 +172,9 @@ void |
| 103 | * |
| 104 | * This call acts as a full compiler and hardware memory barrier. |
| 105 | * |
| 106 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 107 | + * the pointer passed to it should not be `volatile`. |
| 108 | + * |
| 109 | * Returns: %TRUE if the resultant value is zero |
| 110 | * |
| 111 | * Since: 2.4 |
| 112 | @@ -189,6 +201,9 @@ gboolean |
| 113 | * |
| 114 | * This call acts as a full compiler and hardware memory barrier. |
| 115 | * |
| 116 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 117 | + * the pointer passed to it should not be `volatile`. |
| 118 | + * |
| 119 | * Returns: %TRUE if the exchange took place |
| 120 | * |
| 121 | * Since: 2.4 |
| 122 | @@ -216,6 +231,9 @@ gboolean |
| 123 | * Before version 2.30, this function did not return a value |
| 124 | * (but g_atomic_int_exchange_and_add() did, and had the same meaning). |
| 125 | * |
| 126 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 127 | + * the pointer passed to it should not be `volatile`. |
| 128 | + * |
| 129 | * Returns: the value of @atomic before the add, signed |
| 130 | * |
| 131 | * Since: 2.4 |
| 132 | @@ -240,6 +258,9 @@ gint |
| 133 | * Think of this operation as an atomic version of |
| 134 | * `{ tmp = *atomic; *atomic &= val; return tmp; }`. |
| 135 | * |
| 136 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 137 | + * the pointer passed to it should not be `volatile`. |
| 138 | + * |
| 139 | * Returns: the value of @atomic before the operation, unsigned |
| 140 | * |
| 141 | * Since: 2.30 |
| 142 | @@ -264,6 +285,9 @@ guint |
| 143 | * |
| 144 | * This call acts as a full compiler and hardware memory barrier. |
| 145 | * |
| 146 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 147 | + * the pointer passed to it should not be `volatile`. |
| 148 | + * |
| 149 | * Returns: the value of @atomic before the operation, unsigned |
| 150 | * |
| 151 | * Since: 2.30 |
| 152 | @@ -288,6 +312,9 @@ guint |
| 153 | * |
| 154 | * This call acts as a full compiler and hardware memory barrier. |
| 155 | * |
| 156 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 157 | + * the pointer passed to it should not be `volatile`. |
| 158 | + * |
| 159 | * Returns: the value of @atomic before the operation, unsigned |
| 160 | * |
| 161 | * Since: 2.30 |
| 162 | @@ -309,6 +336,9 @@ guint |
| 163 | * This call acts as a full compiler and hardware |
| 164 | * memory barrier (before the get). |
| 165 | * |
| 166 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 167 | + * the pointer passed to it should not be `volatile`. |
| 168 | + * |
| 169 | * Returns: the value of the pointer |
| 170 | * |
| 171 | * Since: 2.4 |
| 172 | @@ -329,6 +359,9 @@ gpointer |
| 173 | * This call acts as a full compiler and hardware |
| 174 | * memory barrier (after the set). |
| 175 | * |
| 176 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 177 | + * the pointer passed to it should not be `volatile`. |
| 178 | + * |
| 179 | * Since: 2.4 |
| 180 | **/ |
| 181 | void |
| 182 | @@ -354,6 +387,9 @@ void |
| 183 | * |
| 184 | * This call acts as a full compiler and hardware memory barrier. |
| 185 | * |
| 186 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 187 | + * the pointer passed to it should not be `volatile`. |
| 188 | + * |
| 189 | * Returns: %TRUE if the exchange took place |
| 190 | * |
| 191 | * Since: 2.4 |
| 192 | @@ -379,6 +415,9 @@ gboolean |
| 193 | * |
| 194 | * This call acts as a full compiler and hardware memory barrier. |
| 195 | * |
| 196 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 197 | + * the pointer passed to it should not be `volatile`. |
| 198 | + * |
| 199 | * Returns: the value of @atomic before the add, signed |
| 200 | * |
| 201 | * Since: 2.30 |
| 202 | @@ -403,6 +442,9 @@ gssize |
| 203 | * |
| 204 | * This call acts as a full compiler and hardware memory barrier. |
| 205 | * |
| 206 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 207 | + * the pointer passed to it should not be `volatile`. |
| 208 | + * |
| 209 | * Returns: the value of @atomic before the operation, unsigned |
| 210 | * |
| 211 | * Since: 2.30 |
| 212 | @@ -427,6 +469,9 @@ gsize |
| 213 | * |
| 214 | * This call acts as a full compiler and hardware memory barrier. |
| 215 | * |
| 216 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 217 | + * the pointer passed to it should not be `volatile`. |
| 218 | + * |
| 219 | * Returns: the value of @atomic before the operation, unsigned |
| 220 | * |
| 221 | * Since: 2.30 |
| 222 | @@ -451,6 +496,9 @@ gsize |
| 223 | * |
| 224 | * This call acts as a full compiler and hardware memory barrier. |
| 225 | * |
| 226 | + * While @atomic has a `volatile` qualifier, this is a historical artifact and |
| 227 | + * the pointer passed to it should not be `volatile`. |
| 228 | + * |
| 229 | * Returns: the value of @atomic before the operation, unsigned |
| 230 | * |
| 231 | * Since: 2.30 |
| 232 | diff --git a/glib/gthread.c b/glib/gthread.c |
| 233 | index 612a9739f..29216d7fd 100644 |
| 234 | --- a/glib/gthread.c |
| 235 | +++ b/glib/gthread.c |
| 236 | @@ -686,6 +686,9 @@ g_once_impl (GOnce *once, |
| 237 | * // use initialization_value here |
| 238 | * ]| |
| 239 | * |
| 240 | + * While @location has a `volatile` qualifier, this is a historical artifact and |
| 241 | + * the pointer passed to it should not be `volatile`. |
| 242 | + * |
| 243 | * Returns: %TRUE if the initialization section should be entered, |
| 244 | * %FALSE and blocks otherwise |
| 245 | * |
| 246 | @@ -725,6 +728,9 @@ gboolean |
| 247 | * releases concurrent threads blocking in g_once_init_enter() on this |
| 248 | * initialization variable. |
| 249 | * |
| 250 | + * While @location has a `volatile` qualifier, this is a historical artifact and |
| 251 | + * the pointer passed to it should not be `volatile`. |
| 252 | + * |
| 253 | * Since: 2.14 |
| 254 | */ |
| 255 | void |
| 256 | -- |
| 257 | 2.30.1 |
| 258 | |