5 Thread safe FIFO data structure, using a List.
6 Useful for working with producer/consumer threads.
9 #ifndef _DRAGONSTD_QUEUE_H_ // include guard
10 #define _DRAGONSTD_QUEUE_H_
12 #include <pthread.h> // for pthread_cond_t, pthread_mutex_t
13 #include <stdbool.h> // for bool
14 #include "list.h" // for List
18 List lst; // list containing data
19 unsigned int cnl: 1; // cancel state
20 unsigned int fin: 1; // finish state
21 pthread_cond_t cnd; // condition variable for notifying consumer
22 pthread_mutex_t mtx; // mutex to protect the condition variable
25 void queue_ini(Queue *queue);
27 Initializes the queue.
29 The queue should be uninitialized or deleted when passed to this function.
32 void queue_dst(Queue *queue);
36 Afterwards, the queue should no longer be used.
38 This does not clear the underling list. Use queue_fin or queue_clr to make sure the
39 list is cleared before calling this function.
42 void queue_clr(Queue *queue, void *iter, void *arg, void *trans);
46 Calls list_clr on the underling list. This is not thread safe. Use queue_fin instead
47 to wait for consumer threads to finish processing the data.
50 bool queue_enq(Queue *queue, void *dat);
53 Enqueues an element to the back of the queue.
54 Returns true if the enqueueing was successful (this is always the case if queue_fin
57 Notifies waiting consumer threads.
60 bool queue_ppd(Queue *queue, void *dat);
63 Enqueues an element at the front of the queue.
64 Returns true if the enqueueing was successful (this is always the case if queue_fin
67 Notifies waiting consumer threads.
70 void *queue_deq(Queue *queue, void *trans);
75 If no element is in the queue, wait until there is one.
76 The (optional) transformer is called once an element is available and has been
77 dequeued and while the queue mutex is still locked.
79 Note the the wait continues if the transformer returns NULL.
82 void queue_cnl(Queue *queue);
86 Subsequent calls to queue_deq immediately return NULL.
89 void queue_fin(Queue *queue); // disallow enqueing, wait until consumption finished
92 Cancels enqueueing and waits for the queue to finish.
93 Subsequent calls to queue_enq have no effect and return false.
95 Before returning, this function waits for the queue to be empty.
98 #endif // _DRAGONSTD_QUEUE_H_