forked from videolan/vlc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
vlc_queue.h
261 lines (236 loc) · 7.22 KB
/
vlc_queue.h
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
259
260
261
/*****************************************************************************
* vlc_queue.h: generic queue functions
*****************************************************************************
* Copyright (C) 2020 Rémi Denis-Courmont
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this program; if not, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
#ifndef VLC_QUEUE_H
#define VLC_QUEUE_H
/**
* @defgroup queue Thread-safe queues (FIFO)
* @ingroup cext
* @{
* @file vlc_queue.h
*/
#include <stdbool.h>
#include <stdint.h>
#include <vlc_common.h>
#include <vlc_threads.h>
/**
* Opaque type for queue entry.
*/
struct vlc_queue_entry;
/**
* Thread-safe queue (a.k.a. FIFO).
*/
typedef struct vlc_queue
{
struct vlc_queue_entry *first;
struct vlc_queue_entry **lastp;
ptrdiff_t next_offset;
vlc_mutex_t lock;
vlc_cond_t wait;
} vlc_queue_t;
/**
* Initializes a queue.
*
* @param queue storage space for the queue
* @param next_offset offset of the pointer to the next element
* within a queue entry (as per @c offsetof())
*/
VLC_API void vlc_queue_Init(vlc_queue_t *queue, ptrdiff_t next_offset);
/**
* @defgroup queue_ll Queue internals
*
* Low-level queue functions.
*
* In some cases, the high-level queue functions do not exactly fit the
* use case requirements, and it is necessary to access the queue internals.
* This typically occurs when threads wait for elements to be added to the
* queue at the same time as some other type of events.
* @{
*/
/**
* Locks a queue.
*
* No more than one thread can lock a queue at any given time, and no other
* thread can modify the queue while it is locked.
* Accordingly, if the queue is already locked by another thread, this function
* waits.
*
* Use vlc_queue_Unlock() to release the lock.
*
* @warning Recursively locking a single queue is undefined.
* Also locking more than one queue at a time may lead to lock inversion:
* mind the locking order!
*/
static inline void vlc_queue_Lock(vlc_queue_t *q)
{
vlc_mutex_lock(&q->lock);
}
/**
* Unlocks a queue.
*
* This releases the lock on a queue, allowing other threads to manipulate the
* queue. The behaviour is undefined if the calling thread is not holding the
* queue lock.
*/
static inline void vlc_queue_Unlock(vlc_queue_t *q)
{
vlc_mutex_unlock(&q->lock);
}
/**
* Wakes one thread waiting for a queue entry up.
*/
static inline void vlc_queue_Signal(vlc_queue_t *q)
{
vlc_cond_signal(&q->wait);
}
/**
* Waits for a queue entry.
*
* @note This function is a cancellation point.
* In case of cancellation, the queue will be locked,
* as is consistent for condition variable semantics.
*
* @bug This function should probably not be aware of cancellation.
*/
static inline void vlc_queue_Wait(vlc_queue_t *q)
{
vlc_cond_wait(&q->wait, &q->lock);
}
/**
* Queues an entry (without locking).
*
* This function enqueues an entry, or rather a linked-list of entries, in a
* thread-safe queue, without taking the queue lock.
*
* @warning It is assumed that the caller already holds the queue lock;
* otherwise the behaviour is undefined.
*
* @param q A queue locked with ::vlc_queue_Lock
* @param entry NULL-terminated list of entries to queue
* (if NULL, this function has no effects)
*/
VLC_API void vlc_queue_EnqueueUnlocked(vlc_queue_t *q, void *entry);
/**
* Dequeues the oldest entry (without locking).
*
* This function dequeues an entry from a thread-safe queue. It is assumed
* that the caller already holds the queue lock; otherwise the behaviour is
* undefined.
*
* @warning It is assumed that the caller already holds the queue lock;
* otherwise the behaviour is undefined.
*
* @return the first entry in the queue, or NULL if the queue is empty
*/
VLC_API void *vlc_queue_DequeueUnlocked(vlc_queue_t *) VLC_USED;
/**
* Dequeues all entries (without locking).
*
* This is equivalent to calling vlc_queue_DequeueUnlocked() repeatedly until
* the queue is emptied. However this function is much faster than that, as it
* does not need to update the linked-list pointers.
*
* @warning It is assumed that the caller already holds the queue lock;
* otherwise the behaviour is undefined.
*
* @return a linked-list of all entries (possibly NULL if none)
*/
VLC_API void *vlc_queue_DequeueAllUnlocked(vlc_queue_t *) VLC_USED;
/**
* Checks if a queue is empty (without locking).
*
* @warning It is assumed that the caller already holds the queue lock;
* otherwise the behaviour is undefined.
*
* @retval false the queue contains one or more entries
* @retval true the queue is empty
*/
VLC_USED static inline bool vlc_queue_IsEmpty(const vlc_queue_t *q)
{
return q->first == NULL;
}
/** @} */
/**
* Queues an entry.
*
* This function enqueues an entry, or rather a linked-list of entries, in a
* thread-safe queue.
*
* @param q A queue initialized with ::vlc_queue_Init
* @param entry list of entries (if NULL, this function has no effects)
*/
VLC_API void vlc_queue_Enqueue(vlc_queue_t *q, void *entry);
/**
* Dequeues the oldest entry.
*
* This function dequeues an entry from a thread-safe queue. If the queue is
* empty, it will wait until at least one entry is available.
*
* @param queue queue object to dequeue an entry from
*
* @return the first entry in the queue, or NULL if the queue is empty
*/
VLC_API void *vlc_queue_Dequeue(vlc_queue_t *queue) VLC_USED;
/**
* Dequeues all entries.
*
* This is equivalent to calling vlc_queue_Dequeue() repeatedly until the queue
* is emptied. However this function is much faster than that, as it
* does not need to update the linked-list pointers.
*
* @return a linked-list of all entries (possibly NULL if none)
*/
VLC_API void *vlc_queue_DequeueAll(vlc_queue_t *) VLC_USED;
/**
* @defgroup queue_killable Killable queues
*
* Thread-safe queues with an end flag.
*
* @{
*/
/**
* Marks a queue ended.
*/
static inline void vlc_queue_Kill(vlc_queue_t *q,
bool *restrict tombstone)
{
vlc_queue_Lock(q);
*tombstone = true;
vlc_queue_Signal(q);
vlc_queue_Unlock(q);
}
/**
* Dequeues one entry from a killable queue.
*
* @return an entry, or NULL if the queue is empty and has been ended.
*/
static inline void *vlc_queue_DequeueKillable(vlc_queue_t *q,
const bool *tombstone)
{
void *entry;
vlc_queue_Lock(q);
while (vlc_queue_IsEmpty(q) && !*tombstone)
vlc_queue_Wait(q);
entry = vlc_queue_DequeueUnlocked(q);
vlc_queue_Unlock(q);
return entry;
}
/** @} */
/** @} */
#endif