update
[cgds.git] / src / Queue.h
1 /**
2 * @file Queue.h
3 */
4
5 #ifndef CGDS_QUEUE_H
6 #define CGDS_QUEUE_H
7
8 #include <stdlib.h>
9 #include <string.h>
10 #include "cgds/types.h"
11 #include "cgds/safe_alloc.h"
12
13 /**
14 * @brief Generic internal queue cell.
15 */
16 typedef struct QueueCell {
17 void* data; ///< Generic data contained in the cell.
18 struct QueueCell* next; ///< Next cell in the internal single-linked list.
19 } QueueCell;
20
21 /**
22 * @brief Queue containing generic data.
23 * @param dataSize Size in bytes of a queue element.
24 */
25 typedef struct Queue {
26 UInt size; ///< Count elements in the queue.
27 size_t dataSize; ///< Size in bytes of a queue element.
28 QueueCell* front; ///< Pointer to the next dequeued element.
29 QueueCell* back; ///< Pointer to the last enqueued element.
30 } Queue;
31
32 /**
33 * @brief Initialize an empty queue.
34 * @param queue "this" pointer.
35 * @param dataSize Size in bytes of a queue element.
36 */
37 void _queue_init(
38 Queue* queue, ///< "this" pointer.
39 size_t dataSize ///< Size in bytes of a queue element.
40 );
41
42 /**
43 * @brief Return an allocated and initialized queue.
44 */
45 Queue* _queue_new(
46 size_t dataSize ///< Size in bytes of a queue element.
47 );
48
49 /**
50 * @brief Return an allocated and initialized queue.
51 * @param type Type of a queue element (int, char*, ...).
52 *
53 * Usage: Queue* queue_new(<Type> type)
54 */
55 #define queue_new(type) \
56 _queue_new(sizeof(type))
57
58 /**
59 * @brief Copy constructor (works well if items do not have allocated sub-pointers).
60 */
61 Queue* queue_copy(
62 Queue* queue ///< "this" pointer.
63 );
64
65 /**
66 * @brief Check if the queue is empty.
67 */
68 Bool queue_empty(
69 Queue* queue ///< "this" pointer.
70 );
71
72 /**
73 * @brief Return size of the current queue.
74 */
75 UInt queue_size(
76 Queue* queue ///< "this" pointer.
77 );
78
79 /**
80 * @brief Add something at the end of the queue.
81 */
82 void _queue_push(
83 Queue* queue, ///< "this" pointer.
84 void* data ///< Data to be pushed.
85 );
86
87 /**
88 * @brief Add something at the end of the queue.
89 * @param queue "this" pointer
90 * @param data Data to be pushed.
91 *
92 * Usage: void queue_push(Queue* queue, void data)
93 */
94 #define queue_push(queue, data) \
95 { \
96 typeof((data)) tmp = data; \
97 _queue_push(queue, &tmp); \
98 }
99
100 /**
101 * @brief Return what is at the beginning of the queue.
102 */
103 void* _queue_peek(
104 Queue* queue ///< "this" pointer.
105 );
106
107 /**
108 * @brief Return what is at the beginning of the queue.
109 * @param queue "this" pointer.
110 * @param data Data to be assigned.
111 *
112 * Usage: void queue_peek(Queue* queue, void data)
113 */
114 #define queue_peek(queue, data) \
115 { \
116 void* pData = _queue_peek(queue); \
117 data = *((typeof(&data))pData); \
118 }
119
120 /**
121 * @brief Remove the beginning of the queue.
122 */
123 void queue_pop(
124 Queue* queue ///< "this" pointer.
125 );
126
127 /**
128 * @brief Clear the entire queue.
129 */
130 void queue_clear(
131 Queue* queue ///< "this" pointer.
132 );
133
134 /**
135 * @brief Destroy the queue: clear it, and free 'queue' pointer.
136 */
137 void queue_destroy(
138 Queue* queue ///< "this" pointer.
139 );
140
141 #endif