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
|
#ifndef BH_QUEUE_H
#define BH_QUEUE_H
#include <bh/bh.h>
typedef struct bh_queue_s bh_queue_t;
/**
* @brief Create new queue object.
*
* @return If the function succeeds, the return value is a pointer to the new
* queue object.
* @return If the function fails, the return value is NULL.
*
* @sa bh_queue_free, bh_queue_reserve, bh_queue_insert
*/
bh_queue_t *bh_queue_new(void);
/**
* @brief Free queue object.
*
* @param queue Valid pointer to the queue object.
*
* @sa bh_queue_clear
*/
void bh_queue_free(bh_queue_t *queue);
/**
* @brief Clear the queue.
*
* @param queue Valid pointer to the queue object.
*
* @warning Clearing the queue does invalidate iterators.
*
* @sa bh_queue_remove
*/
void bh_queue_clear(bh_queue_t *queue);
/**
* @brief Reserve space for the specified amount of elements.
*
* @param queue Valid pointer to the queue object.
* @param size The amount of elements.
*
* @return If the function succeeds, the return value is zero.
* @return If the function fails, the return value is non-zero.
*
* @warning Reserving queue space does invalidate iterators.
*
* @sa bh_queue_capacity, bh_queue_insert
*/
int bh_queue_reserve(bh_queue_t *queue,
size_t size);
/**
* @brief Insert element at the end of the queue.
*
* @param queue Valid pointer to the queue object.
* @param value Element.
*
* @return If the function succeeds, the return value is zero.
* @return If the function fails, the return value is non-zero.
*
* @warning Inserted element is owned by the caller of the function.
* @warning Inserting elements into the queue does invalidate iterators.
*
* @sa bh_queue_remove, bh_queue_front
*/
int bh_queue_insert(bh_queue_t *queue,
void *value);
/**
* @brief Remove element from the front of the queue.
*
* @param queue Valid pointer to the queue object.
*
* @warning Removing elements from the queue does invalidate iterators.
*
* @sa bh_queue_insert, bh_queue_front
*/
void bh_queue_remove(bh_queue_t *queue);
/**
* @brief Return element from the front of the queue.
*
* @param queue Valid pointer to the queue object.
*
* @return If the function succeeds, the return value is a valid pointer to
* the element.
* @return If the function fails, the return value is NULL.
*
* @note If the queue is empty, function will fail to return element from
* the queue.
*
* @sa bh_queue_empty, bh_queue_insert
*/
void *bh_queue_front(bh_queue_t *queue);
/**
* @brief Check if the queue is empty.
*
* @param queue Valid pointer to the queue object.
*
* @return The return value is non-zero if the queue is empty, otherwise zero.
*
* @sa bh_queue_size
*/
int bh_queue_empty(bh_queue_t *queue);
/**
* @brief Return queue size.
*
* @param queue Valid pointer to the queue object.
*
* @return The return value is current queue size.
*
* @sa bh_queue_empty, bh_queue_capacity
*/
size_t bh_queue_size(bh_queue_t *queue);
/**
* @brief Return queue capacity.
*
* @param queue Valid pointer to the queue object.
*
* @return The return value is current queue capacity.
*
* @sa bh_queue_reserve, bh_queue_size
*/
size_t bh_queue_capacity(bh_queue_t *queue);
/**
* @brief Return iterator for the next element in the queue.
*
* @param queue Valid pointer to the queue object.
* @param iter Valid or NULL iterator.
*
* @return The return value is the valid iterator for the next element in the
* queue.
* @return The return value is the NULL iterator if there is no more elements
* in the queue.
*
* @sa bh_queue_iter_value
*/
void *bh_queue_iter_next(bh_queue_t *queue,
void *iter);
/**
* @brief Return pointer to the element's value.
*
* @param iter Valid iterator.
*
* @return The return value is the stored element.
*
* @sa bh_queue_iter_next
*/
void *bh_queue_iter_value(void *iter);
#endif /* BH_QUEUE_H */
|
