1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
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
|
