• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!-- ##### SECTION Title ##### -->
2Asynchronous Queues
3
4<!-- ##### SECTION Short_Description ##### -->
5asynchronous communication between threads
6
7<!-- ##### SECTION Long_Description ##### -->
8<para>
9Often you need to communicate between different threads. In general
10it's safer not to do this by shared memory, but by explicit message
11passing. These messages only make sense asynchronously for
12multi-threaded applications though, as a synchronous operation could as
13well be done in the same thread.
14</para>
15
16<para>
17Asynchronous queues are an exception from most other GLib data
18structures, as they can be used simultaneously from multiple threads
19without explicit locking and they bring their own builtin reference
20counting. This is because the nature of an asynchronous queue is that
21it will always be used by at least 2 concurrent threads.
22</para>
23
24<para>
25For using an asynchronous queue you first have to create one with
26g_async_queue_new(). A newly-created queue will get the reference
27count 1. Whenever another thread is creating a new reference of (that
28is, pointer to) the queue, it has to increase the reference count
29(using g_async_queue_ref()). Also, before removing this reference, the
30reference count has to be decreased (using
31g_async_queue_unref()). After that the queue might no longer exist so
32you must not access it after that point.
33</para>
34
35<para>
36A thread, which wants to send a message to that queue simply calls
37g_async_queue_push() to push the message to the queue.
38</para>
39
40<para>
41A thread, which is expecting messages from an asynchronous queue
42simply calls g_async_queue_pop() for that queue. If no message is
43available in the queue at that point, the thread is now put to sleep
44until a message arrives. The message will be removed from the queue
45and returned. The functions g_async_queue_try_pop() and
46g_async_queue_timed_pop() can be used to only check for the presence
47of messages or to only wait a certain time for messages respectively.
48</para>
49
50<para>
51For almost every function there exist two variants, one that locks the
52queue and one that doesn't. That way you can hold the queue lock
53(acquire it with g_async_queue_lock() and release it with
54g_async_queue_unlock()) over multiple queue accessing
55instructions. This can be necessary to ensure the integrity of the
56queue, but should only be used when really necessary, as it can make
57your life harder if used unwisely. Normally you should only use the
58locking function variants (those without the suffix _unlocked)
59</para>
60
61<!-- ##### SECTION See_Also ##### -->
62<para>
63
64</para>
65
66<!-- ##### SECTION Stability_Level ##### -->
67
68
69<!-- ##### STRUCT GAsyncQueue ##### -->
70<para>
71The #GAsyncQueue struct is an opaque data structure, which represents
72an asynchronous queue. It should only be accessed through the
73<function>g_async_queue_*</function> functions.
74</para>
75
76
77<!-- ##### FUNCTION g_async_queue_new ##### -->
78
79
80@Returns:
81
82
83<!-- ##### FUNCTION g_async_queue_new_full ##### -->
84<para>
85
86</para>
87
88@item_free_func:
89@Returns:
90
91
92<!-- ##### FUNCTION g_async_queue_ref ##### -->
93
94
95@queue:
96@Returns:
97
98
99<!-- ##### FUNCTION g_async_queue_unref ##### -->
100
101
102@queue:
103
104
105<!-- ##### FUNCTION g_async_queue_push ##### -->
106
107
108@queue:
109@data:
110
111
112<!-- ##### FUNCTION g_async_queue_push_sorted ##### -->
113<para>
114
115</para>
116
117@queue:
118@data:
119@func:
120@user_data:
121
122
123<!-- ##### FUNCTION g_async_queue_pop ##### -->
124
125
126@queue:
127@Returns:
128
129
130<!-- ##### FUNCTION g_async_queue_try_pop ##### -->
131
132
133@queue:
134@Returns:
135
136
137<!-- ##### FUNCTION g_async_queue_timed_pop ##### -->
138
139
140@queue:
141@end_time:
142@Returns:
143
144
145<!-- ##### FUNCTION g_async_queue_length ##### -->
146
147
148@queue:
149@Returns:
150
151
152<!-- ##### FUNCTION g_async_queue_sort ##### -->
153<para>
154
155</para>
156
157@queue:
158@func:
159@user_data:
160
161
162<!-- ##### FUNCTION g_async_queue_lock ##### -->
163
164
165@queue:
166
167
168<!-- ##### FUNCTION g_async_queue_unlock ##### -->
169
170
171@queue:
172
173
174<!-- ##### FUNCTION g_async_queue_ref_unlocked ##### -->
175
176
177@queue:
178
179
180<!-- ##### FUNCTION g_async_queue_unref_and_unlock ##### -->
181
182
183@queue:
184
185
186<!-- ##### FUNCTION g_async_queue_push_unlocked ##### -->
187
188
189@queue:
190@data:
191
192
193<!-- ##### FUNCTION g_async_queue_push_sorted_unlocked ##### -->
194<para>
195
196</para>
197
198@queue:
199@data:
200@func:
201@user_data:
202
203
204<!-- ##### FUNCTION g_async_queue_pop_unlocked ##### -->
205
206
207@queue:
208@Returns:
209
210
211<!-- ##### FUNCTION g_async_queue_try_pop_unlocked ##### -->
212
213
214@queue:
215@Returns:
216
217
218<!-- ##### FUNCTION g_async_queue_timed_pop_unlocked ##### -->
219
220
221@queue:
222@end_time:
223@Returns:
224
225
226<!-- ##### FUNCTION g_async_queue_length_unlocked ##### -->
227
228
229@queue:
230@Returns:
231
232
233<!-- ##### FUNCTION g_async_queue_sort_unlocked ##### -->
234<para>
235
236</para>
237
238@queue:
239@func:
240@user_data:
241
242
243