Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kQueue.h
Go to the documentation of this file.
1 /**
2 * @file kQueue.h
3 * @brief Declares the kQueue class.
4 *
5 * @internal
6 * Copyright (C) 2005-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #ifndef K_API_QUEUE_H
11 #define K_API_QUEUE_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @class kQueue
19 * @extends kObject
20 * @implements kCollection
21 * @ingroup kApi-Data
22 * @brief Represents a FIFO queue implemented with a dynamic array.
23 *
24 * kQueue represents a dynamic, array-based queue of objects or values. The kQueue constructor
25 * accepts a kType value that determines the type of items that will be stored in the queue. The queue will
26 * automatically grow as new items are added.
27 *
28 * @code
29 * kStatus QueueExample()
30 * {
31 * kQueue queue = kNULL;
32 * k32s values[] = { 1, 2, 3, 5, 7, 9 };
33 * kSize i;
34 *
35 * kTry
36 * {
37 * //create a queue that can store 32-bit integers
38 * kTest(kQueue_Construct(&queue, kTypeOf(k32s), 0, kNULL));
39 *
40 * //add some initial items to the queue
41 * for (i = 0; i < kCountOf(values); ++i)
42 * {
43 * kTest(kQueue_Add(queue, &values[i]);
44 * }
45 *
46 * //print some information about the queue and its items
47 * printf("Item type: %s\n", kType_Name(kQueue_ItemType(queue)));
48 * printf("Count: %u\n", (k32u) kQueue_Count(queue));
49 *
50 * for (i = 0; i < kQueue_Count(queue); ++i)
51 * {
52 * //the kQueue_As_ macro can be used to get a queue item and cast it to the desired type;
53 * //this is equivalent to *(k32s*)kQueue_At(queue, i);
54 * k32s value = kQueue_As_(queue, i, k32s);
55 *
56 * printf("Item %u: %d\n", (k32u)i, value);
57 * }
58 * }
59 * kFinally
60 * {
61 * kObject_Destroy(queue);
62 *
63 * kEndFinally();
64 * }
65 *
66 * return kOK;
67 * }
68 *
69 * @endcode
70 *
71 * For queues that contain <em>objects</em> (e.g. kImage) as opposed to <em>values</em> (e.g. k32s), the objects
72 * are not automatically destroyed when the queue is destroyed. To recursively destroy both the queue and the
73 * queue items, use kObject_Dispose.
74 */
75 //typedef kObject kQueue; --forward-declared in kApiDef.x.h
76
77 /**
78 * Constructs a kQueue object.
79 *
80 * @public @memberof kQueue
81 * @param queue Receives constructed queue object.
82 * @param itemType Type of queue element.
83 * @param initialCapacity Capacity initially reserved for queue items.
84 * @param allocator Memory allocator (or kNULL for default).
85 * @return Operation status.
86 */
87 kFx(kStatus) kQueue_Construct(kQueue* queue, kType itemType, kSize initialCapacity, kAlloc allocator);
88
89 /**
90 * Reallocates the queue item buffer.
91 *
92 * @public @memberof kQueue
93 * @param queue Queue object.
94 * @param itemType Type of queue element.
95 * @param initialCapacity Capacity initially reserved for queue items.
96 * @return Operation status.
97 */
98 kFx(kStatus) kQueue_Allocate(kQueue queue, kType itemType, kSize initialCapacity);
99
100 /**
101 * Performs a shallow copy of the source queue.
102 *
103 * Source items are copied by value; if the source queue contains objects, the object
104 * handles are copied but the objects are not cloned.
105 *
106 * @public @memberof kQueue
107 * @param queue Queue object.
108 * @param source Source queue to be copied.
109 * @return Operation status.
110 */
111 kFx(kStatus) kQueue_Assign(kQueue queue, kQueue source);
112
113 /**
114 * Sets the count of queue items to zero.
115 *
116 * @public @memberof kQueue
117 * @param queue Queue object.
118 * @return Operation status.
119 */
120 kFx(kStatus) kQueue_Clear(kQueue queue);
121
122 /**
123 * Disposes any elements in the queue and sets the count of queue items to zero.
124 *
125 * @public @memberof kQueue
126 * @param queue Queue object.
127 * @return Operation status.
128 */
129 kFx(kStatus) kQueue_Purge(kQueue queue);
130
131 /**
132 * Ensures that capacity is reserved for at least the specified number of queue items.
133 *
134 * Existing queue items are preserved.
135 *
136 * @public @memberof kQueue
137 * @param queue Queue object.
138 * @param capacity Queue capacity, in items.
139 * @return Operation status.
140 */
141 kFx(kStatus) kQueue_Reserve(kQueue queue, kSize capacity);
142
143 /**
144 * Adds the specified item to the end of the queue.
145 *
146 * @public @memberof kQueue
147 * @param queue Queue object.
148 * @param item Pointer to item that will be copied (by value) into the queue.
149 * @return Operation status.
150 */
151 kFx(kStatus) kQueue_Add(kQueue queue, const void* item);
152
153 /**
154 * Removes the item at the head of the queue.
155 *
156 * @public @memberof kQueue
157 * @param queue Queue object.
158 * @param item Destination for the removed item (copied by value, can be null).
159 * @return Operation status.
160 */
161 kFx(kStatus) kQueue_Remove(kQueue queue, void* item);
162
163 /**
164 * Sets the value of an item.
165 *
166 * @public @memberof kQueue
167 * @param queue Queue object.
168 * @param index Item index.
169 * @param item Item that will be copied into the queue.
170 * @return Operation status.
171 */
172 kFx(kStatus) kQueue_SetItem(kQueue queue, kSize index, const void* item);
173
174 /**
175 * Gets the value of an item.
176 *
177 * @public @memberof kQueue
178 * @param queue Queue object.
179 * @param index Item index.
180 * @param item Destination for item that will be copied (by value) from the queue.
181 * @return Operation status.
182 */
183 kFx(kStatus) kQueue_Item(kQueue queue, kSize index, void* item);
184
185 /**
186 * Increases the queue count by the specified amount.
187 *
188 * Increases queue capacity if necessary; existing queue items are preserved.
189 * New items are not initialized.
190 *
191 * @public @memberof kQueue
192 * @param queue Queue object.
193 * @param count Amount to add to the existing count.
194 * @return Operation status.
195 */
196 kFx(kStatus) kQueue_AddCount(kQueue queue, kSize count);
197
198 /**
199 * Decreases the queue count by the specified amount.
200 *
201 * @public @memberof kQueue
202 * @param queue Queue object.
203 * @param count Amount to remove from the existing count.
204 * @return Operation status.
205 */
206 kFx(kStatus) kQueue_RemoveCount(kQueue queue, kSize count);
207
208 /**
209 * Returns a pointer to the specified item in the queue buffer.
210 *
211 * @public @memberof kQueue
212 * @param queue Queue object.
213 * @param index Item index.
214 * @return Pointer to queue element.
215 */
216 kFx(void*) kQueue_At(kQueue queue, kSize index);
217
218 /**
219 * Returns the queue element type.
220 *
221 * @public @memberof kQueue
222 * @param queue Queue object.
223 * @return Item type.
224 */
225 kFx(kType) kQueue_ItemType(kQueue queue);
226
227 /**
228 * Returns the queue element size.
229 *
230 * @public @memberof kQueue
231 * @param queue Queue object.
232 * @return Item size, in bytes.
233 */
234 kFx(kSize) kQueue_ItemSize(kQueue queue);
235
236 /**
237 * Returns the current count of items in the queue.
238 *
239 * @public @memberof kQueue
240 * @param queue Queue object.
241 * @return Current count of items.
242 */
243 kFx(kSize) kQueue_Count(kQueue queue);
244
245 /**
246 * Returns the number of elements for which space has been allocated.
247 *
248 * @public @memberof kQueue
249 * @param queue Queue object.
250 * @return Queue capacity.
251 */
252 kFx(kSize) kQueue_Capacity(kQueue queue);
253
254 #define kQueue_AddCount_(QUEUE, C) kxQueue_AddCount_(QUEUE, C) ///< Macro version of kQueue_AddCount.
255 #define kQueue_RemoveCount_(QUEUE, C) kxQueue_RemoveCount_(QUEUE, C) ///< Macro version of kQueue_RemoveCount.
256 #define kQueue_Clear_(QUEUE) kxQueue_Clear_(QUEUE) ///< Macro version of kQueue_Clear.
257 #define kQueue_ItemType_(QUEUE) kxQueue_ItemType_(QUEUE) ///< Macro version of kQueue_ItemType.
258 #define kQueue_ItemSize_(QUEUE) kxQueue_ItemSize_(QUEUE) ///< Macro version of kQueue_ItemSize.
259 #define kQueue_Count_(QUEUE) kxQueue_Count_(QUEUE) ///< Macro version of kQueue_Count.
260 #define kQueue_Capacity_(QUEUE) kxQueue_Capacity_(QUEUE) ///< Macro version of kQueue_Capacity.
261 #define kQueue_At_(QUEUE, INDEX) kxQueue_At_(QUEUE, INDEX) ///< Macro version of kQueue_At.
262
263 /** Accesses a queue element at the specified index, and casts the value to the specified type. */
264 #define kQueue_As_(QUEUE, INDEX, TYPE) kxQueue_As_(QUEUE, INDEX, TYPE)
265
266 kEndHeader()
267
268 #include <kApi/Data/kQueue.x.h>
269
270 #endif
kQueue::kQueue_ItemSize
kSize kQueue_ItemSize(kQueue queue)
Returns the queue element size.
kQueue::kQueue_ItemType
kType kQueue_ItemType(kQueue queue)
Returns the queue element type.
kQueue::kQueue_Construct
kStatus kQueue_Construct(kQueue *queue, kType itemType, kSize initialCapacity, kAlloc allocator)
Constructs a kQueue object.
kQueue::kQueue_SetItem
kStatus kQueue_SetItem(kQueue queue, kSize index, const void *item)
Sets the value of an item.
kQueue::kQueue_Remove
kStatus kQueue_Remove(kQueue queue, void *item)
Removes the item at the head of the queue.
kQueue::kQueue_Allocate
kStatus kQueue_Allocate(kQueue queue, kType itemType, kSize initialCapacity)
Reallocates the queue item buffer.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kQueue::kQueue_Reserve
kStatus kQueue_Reserve(kQueue queue, kSize capacity)
Ensures that capacity is reserved for at least the specified number of queue items.
kQueue::kQueue_Item
kStatus kQueue_Item(kQueue queue, kSize index, void *item)
Gets the value of an item.
kQueue::kQueue_Assign
kStatus kQueue_Assign(kQueue queue, kQueue source)
Performs a shallow copy of the source queue.
kQueue::kQueue_Count
kSize kQueue_Count(kQueue queue)
Returns the current count of items in the queue.
kQueue::kQueue_Clear
kStatus kQueue_Clear(kQueue queue)
Sets the count of queue items to zero.
kQueue::kQueue_Purge
kStatus kQueue_Purge(kQueue queue)
Disposes any elements in the queue and sets the count of queue items to zero.
kQueue::kQueue_Add
kStatus kQueue_Add(kQueue queue, const void *item)
Adds the specified item to the end of the queue.
kApiDef.h
Essential API declarations.
kMsgQueue
Represents a synchronized FIFO queue with an optional maximum size or count capacity.
kQueue::kQueue_At
void * kQueue_At(kQueue queue, kSize index)
Returns a pointer to the specified item in the queue buffer.
kType
Represents metadata about a type (class, interface, or value).
kQueue
Represents a FIFO queue implemented with a dynamic array.
kStatus
Represents an enumeration of error codes.
kQueue::kQueue_RemoveCount
kStatus kQueue_RemoveCount(kQueue queue, kSize count)
Decreases the queue count by the specified amount.
kQueue::kQueue_Capacity
kSize kQueue_Capacity(kQueue queue)
Returns the number of elements for which space has been allocated.
kQueue::kQueue_AddCount
kStatus kQueue_AddCount(kQueue queue, kSize count)
Increases the queue count by the specified amount.