Zen API

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

All Classes Files Functions Variables Typedefs Macros Groups Pages
kMsgQueue.h
Go to the documentation of this file.
1 /**
2 * @file kMsgQueue.h
3 * @brief Declares the kMsgQueue class.
4 *
5 * @internal
6 * Copyright (C) 2011-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_MSG_QUEUE_H
11 #define K_API_MSG_QUEUE_H
12
13 #include <kApi/kApiDef.h>
14
15 kBeginHeader()
16
17 /**
18 * @struct kMsgQueueDropArgs
19 * @ingroup kApi-Threads
20 * @brief Represents arguments passed in a kMsgQueue drop callback.
21 */
22 typedef struct kMsgQueueDropArgs
23 {
24 void* item; ///< Pointer to the item to be dropped.
25 } kMsgQueueDropArgs;
26
27 /**
28 * @class kMsgQueue
29 * @extends kObject
30 * @ingroup kApi-Threads
31 * @brief Represents a synchronized FIFO queue with an optional maximum size or count capacity.
32 */
33 //typedef kObject kMsgQueue; // --forward-declared in kApiDef.x.h
34
35 /** Defines the signature of a callback function to handle dropped items. */
36 typedef kStatus (kCall *kMsgQueueDropFx) (kPointer receiver, kMsgQueue queue, kMsgQueueDropArgs* args);
37
38 /**
39 * Constructs a kMsgQueue object.
40 *
41 * @public @memberof kMsgQueue
42 * @param queue Receives a handle to the constructed object.
43 * @param itemType Type of list element (must be a reference type).
44 * @param allocator Memory allocator (or kNULL for default).
45 * @return Operation status.
46 */
47 kFx(kStatus) kMsgQueue_Construct(kMsgQueue* queue, kType itemType, kAlloc allocator);
48
49 /**
50 * Adjusts the maximum amount of data retained by the queue.
51 *
52 * @public @memberof kMsgQueue
53 * @param queue Queue object.
54 * @param size Maximum total recursive size of all data items in queue, in bytes.
55 * @return Operation status.
56 */
57 kFx(kStatus) kMsgQueue_SetMaxSize(kMsgQueue queue, kSize size);
58
59 /**
60 * Adjusts the maximum count of items retained by the queue.
61 *
62 * @public @memberof kMsgQueue
63 * @param queue Queue object.
64 * @param count Maximum total count of all data items in queue.
65 * @return Operation status.
66 */
67 kFx(kStatus) kMsgQueue_SetMaxCount(kMsgQueue queue, kSize count);
68
69 /**
70 * Reserves memory for the specified number of items.
71 *
72 * @public @memberof kMsgQueue
73 * @param queue Queue object.
74 * @param count Count of items for which to reserve capacity.
75 * @return Operation status.
76 */
77 kFx(kStatus) kMsgQueue_Reserve(kMsgQueue queue, kSize count);
78
79 /**
80 * Sets the callback used when dropping an item.
81 *
82 * If a handler is not set, and the queue contains objects, then dropped objects are passed
83 * to kObject_Dispose.
84 *
85 * @public @memberof kMsgQueue
86 * @param queue Queue object.
87 * @param onDrop Callback function.
88 * @param receiver Callback context.
89 * @return Operation status.
90 */
91 kFx(kStatus) kMsgQueue_SetDropHandler(kMsgQueue queue, kMsgQueueDropFx onDrop, kPointer receiver);
92
93 /**
94 * Adds an item to the queue.
95 *
96 * If queue capacity is exceeded, the oldest item in the queue will be removed. If a drop handler is
97 * installed, the handler will be called; otherwise, if the queue is an object container, then
98 * kObject_Dispose will be used to dispose the item.
99 *
100 * If the operation status returned by this function indicates an error, it is the responsibility
101 * of the caller to dispose the item (if appropriate).
102 *
103 * @public @memberof kMsgQueue
104 * @param queue Queue object.
105 * @param item Item to be added.
106 * @return Operation status.
107 */
108 kFx(kStatus) kMsgQueue_Add(kMsgQueue queue, void* item);
109
110 /**
111 * Removes an item from the queue.
112 *
113 * @public @memberof kMsgQueue
114 * @param queue Queue object.
115 * @param item Receives removed item (can be kNULL).
116 * @param timeout Timeout (microseconds).
117 * @return Operation status.
118 */
119 kFx(kStatus) kMsgQueue_Remove(kMsgQueue queue, void* item, k64u timeout);
120
121 /**
122 * Removes all items from the queue.
123 *
124 * This method does not call the drop handler when removing items.
125 *
126 * @public @memberof kMsgQueue
127 * @param queue Queue object.
128 * @return Operation status.
129 */
130 kFx(kStatus) kMsgQueue_Clear(kMsgQueue queue);
131
132 /**
133 * Disposes any elements in the queue and sets the count of queue items to zero.
134 *
135 * This method does not call the drop handler when removing items.
136 *
137 * @public @memberof kMsgQueue
138 * @param queue Queue object.
139 * @return Operation status.
140 */
141 kFx(kStatus) kMsgQueue_Purge(kMsgQueue queue);
142
143 /**
144 * Reports the current count of queue items.
145 *
146 * @public @memberof kMsgQueue
147 * @param queue Queue object.
148 * @return Count of queue items.
149 */
150 kFx(kSize) kMsgQueue_Count(kMsgQueue queue);
151
152 /**
153 * Reports the maximum total data size of all items in the queue.
154 *
155 * @public @memberof kMsgQueue
156 * @param queue Queue object.
157 * @return Maximum total recursive data size, in bytes.
158 */
159 kFx(kSize) kMsgQueue_MaxSize(kMsgQueue queue);
160
161 /**
162 * Reports the maximum count of items in the queue.
163 *
164 * @public @memberof kMsgQueue
165 * @param queue Queue object.
166 * @return Maximum count of items.
167 */
168 kFx(kSize) kMsgQueue_MaxCount(kMsgQueue queue);
169
170 /**
171 * Reports the type of element stored in the queue.
172 *
173 * @public @memberof kMsgQueue
174 * @param queue Queue object.
175 * @return Capacity of queue (bytes).
176 */
177 kFx(kType) kMsgQueue_ItemType(kMsgQueue queue);
178
179 /**
180 * Reports the current amount of data stored in the queue (in bytes).
181 *
182 * @public @memberof kMsgQueue
183 * @param queue Queue object.
184 * @return Size of queue (bytes).
185 */
186 kFx(kSize) kMsgQueue_DataSize(kMsgQueue queue);
187
188 /**
189 * Reports the count of dropped items.
190 *
191 * @public @memberof kMsgQueue
192 * @param queue Queue object.
193 * @return Count of dropped items.
194 */
195 kFx(k64u) kMsgQueue_DropCount(kMsgQueue queue);
196
197 kEndHeader()
198
199 #include <kApi/Threads/kMsgQueue.x.h>
200
201 #endif
kMsgQueue::kMsgQueue_MaxSize
kSize kMsgQueue_MaxSize(kMsgQueue queue)
Reports the maximum total data size of all items in the queue.
kMsgQueue::kMsgQueue_DropCount
k64u kMsgQueue_DropCount(kMsgQueue queue)
Reports the count of dropped items.
k64u
Represents a 64-bit unsigned integer.
kPointer
Represents a void pointer.
kMsgQueue::kMsgQueue_DataSize
kSize kMsgQueue_DataSize(kMsgQueue queue)
Reports the current amount of data stored in the queue (in bytes).
kMsgQueue::kMsgQueue_SetDropHandler
kStatus kMsgQueue_SetDropHandler(kMsgQueue queue, kMsgQueueDropFx onDrop, kPointer receiver)
Sets the callback used when dropping an item.
kMsgQueue::kMsgQueue_SetMaxSize
kStatus kMsgQueue_SetMaxSize(kMsgQueue queue, kSize size)
Adjusts the maximum amount of data retained by the queue.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kMsgQueue::kMsgQueue_Reserve
kStatus kMsgQueue_Reserve(kMsgQueue queue, kSize count)
Reserves memory for the specified number of items.
kMsgQueue::kMsgQueue_SetMaxCount
kStatus kMsgQueue_SetMaxCount(kMsgQueue queue, kSize count)
Adjusts the maximum count of items retained by the queue.
kStatus
typedef kStatus(kCall *kMsgQueueDropFx)(kPointer receiver
Defines the signature of a callback function to handle dropped items.
kMsgQueue::kMsgQueue_Add
kStatus kMsgQueue_Add(kMsgQueue queue, void *item)
Adds an item to the queue.
kMsgQueue::kMsgQueue_Purge
kStatus kMsgQueue_Purge(kMsgQueue queue)
Disposes any elements in the queue and sets the count of queue items to zero.
kMsgQueue::kMsgQueue_Construct
kStatus kMsgQueue_Construct(kMsgQueue *queue, kType itemType, kAlloc allocator)
Constructs a kMsgQueue object.
kMsgQueue::kMsgQueue_Remove
kStatus kMsgQueue_Remove(kMsgQueue queue, void *item, k64u timeout)
Removes an item from the queue.
kMsgQueue::kMsgQueue_Clear
kStatus kMsgQueue_Clear(kMsgQueue queue)
Removes all items from the queue.
kMsgQueue::kMsgQueue_ItemType
kType kMsgQueue_ItemType(kMsgQueue queue)
Reports the type of element stored in the queue.
kApiDef.h
Essential API declarations.
kMsgQueue
Represents a synchronized FIFO queue with an optional maximum size or count capacity.
kMsgQueueDropArgs
Represents arguments passed in a kMsgQueue drop callback.
Definition: kMsgQueue.h:22
kType
Represents metadata about a type (class, interface, or value).
kMsgQueue::kMsgQueue_Count
kSize kMsgQueue_Count(kMsgQueue queue)
Reports the current count of queue items.
kStatus
Represents an enumeration of error codes.
kCall
#define kCall
kApi standard function calling convention.
Definition: kApiDef.h:17
kMsgQueue::kMsgQueue_MaxCount
kSize kMsgQueue_MaxCount(kMsgQueue queue)
Reports the maximum count of items in the queue.
kMsgQueueDropArgs::item
void * item
Pointer to the item to be dropped.
Definition: kMsgQueue.h:24