Zen API

- Home
- Topics
- Types
- Files

All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
Public Member Functions
kMsgQueue Class Reference
kApi/Threads

## Description

Represents a synchronized FIFO queue with an optional maximum content size and/or item capacity.

kMsgQueue is typically used to exchange data between threads. kMsgQueue supports multiple producers and multiple consumers, but is not strictly fair. Most kMsgQueue methods are thread-safe.

Limits can be placed on the maximum number of items (kMsgQueue_SetMaxCount) and/or maximum total data capacity (kMsgQueue_SetMaxSize). Data capacity limits rely on the type system. For reference types, the size of each item is calculated by calling kObject_Size. For value types, the size of each item is determined by calling kType_Size on the 'itemType' constructor argument.

kMsgQueue supports blocking with a timeout when removing an item from the queue. This enables consumers to efficiently wait for an item to become available.

When adding an item, if capacity limits are set and queue capacity is exceeded, the oldest item in the queue will be dropped. By default, kObject_Dispose will be called for dropped reference items. A custom drop handler can be installed using the kMsgQueue_SetDropHandler method. A count of dropped items can be determined using the kMsgQueue_DropCount method.

With the kMsgQueue_AddEx method, items can be designated as "critical". Critical items are not subject to queue capacity constraints. This provides support for two different kinds of traffic within a single queue: normal items that can be dropped, and critical items that cannot be dropped. This feature is most commonly used to embed special control messages within a stream of non-essential messages.

kStatus MsgQueueExample()
{
kMsgQueue queue = kNULL;
kThread thread = kNULL;
kObject quitMsg = kNULL;
kSize i;
kTry
{
//create a queue that can store images
kTest(kMsgQueue_Construct(&queue, kTypeOf(kImage), kNULL));
//create a consumer thread and pass the queue as the thread entry argument
kTest(kThread_Construct(&thread, kNULL));
kTest(kThread_Start(thread, MsgProcessingThreadEntry, queue));
//create some work for the thread
for (i = 0; i < 5; ++i)
{
kImage image = kNULL;
kTest(kImage_Construct(&image, kTypeOf(k8u), 1024, 1024, kNULL));
kTest(kMsgQueue_Add(queue, &image));
}
//request the thread to terminate
kTest(kMsgQueue_Add(queue, &quitMsg));
}
kFinally
{
//destroying the thread will join automatically
kObject_Destroy(thread);
//disposing the queue will also destroy any images remaining in the queue
kObject_Dispose(queue);
kEndFinally();
}
return kOK;
}
//process messages until a 'quit' (null) message is received
kStatus MsgProcessingThreadEntry(kMsgQueue queue)
{
kImage image = kNULL;
while (kSuccess(kMsgQueue_Remove(queue, &image, kINFINITE)) && !kIsNull(image))
{
//process the image
//...
//clean up
kObject_Destroy(image);
}
return kOK;
}

kMsgQueue supports the kObject_Dispose and kObject_Size methods.

Inheritance diagram for kMsgQueue:

## Public Member Functions
kStatus | kMsgQueue_Add (kMsgQueue queue, void *item)
| Adds an item to the queue. More...
kStatus | kMsgQueue_AddEx (kMsgQueue queue, void *item, kMsgQueueItemOption options)
| Adds an item to the queue with the specified options. More...
kStatus | kMsgQueue_Clear (kMsgQueue queue)
| Removes all items from the queue. More...
kStatus | kMsgQueue_Construct (kMsgQueue *queue, kType itemType, kAlloc allocator)
| Constructs a kMsgQueue object. More...
kSize | kMsgQueue_Count (kMsgQueue queue)
| Reports the current count of queue items. More...
kSize | kMsgQueue_DataSize (kMsgQueue queue)
| Reports the current amount of data stored in the queue (in bytes). More...
k64u | kMsgQueue_DropCount (kMsgQueue queue)
| Reports the count of dropped items. More...
kSize | kMsgQueue_ItemSize (kQueue queue)
| Returns the queue element size. More...
kType | kMsgQueue_ItemType (kMsgQueue queue)
| Reports the type of element stored in the queue. More...
kSize | kMsgQueue_MaxCount (kMsgQueue queue)
| Reports the maximum count of items in the queue. More...
kSize | kMsgQueue_MaxSize (kMsgQueue queue)
| Reports the maximum total data size of all items in the queue. More...
kStatus | kMsgQueue_Purge (kMsgQueue queue)
| Removes and disposes all items from the queue. More...
kStatus | kMsgQueue_PurgeEx (kMsgQueue queue, kMsgQueuePurgeOption options)
| Removes items from the queue using the specified options. More...
kStatus | kMsgQueue_Remove (kMsgQueue queue, void *item, k64u timeout)
| Removes an item from the queue. More...
kStatus | kMsgQueue_Reserve (kMsgQueue queue, kSize count)
| Reserves memory for the specified number of items. More...
kStatus | kMsgQueue_SetDropHandler (kMsgQueue queue, kMsgQueueDropFx onDrop, kPointer receiver)
| Sets the callback used when dropping an item. More...
kStatus | kMsgQueue_SetMaxCount (kMsgQueue queue, kSize count)
| Sets the maximum count of items retained by the queue. More...
kStatus | kMsgQueue_SetMaxSize (kMsgQueue queue, kSize size)
| Sets the maximum amount of data retained by the queue. More...
Public Member Functions inherited from kObject
kAlloc | kObject_Alloc (kObject object)
| Gets the memory allocator associated with this object. More...
kStatus | kObject_Clone (kObject *object, kObject source, kAlloc allocator)
| Constructs a new object by copying an existing object, including any aggregated child elements. More...
kStatus | kObject_Destroy (kObject object)
| Destroys the object. More...
kStatus | kObject_Dispose (kObject object)
| Destroys the object and any aggregated child elements. More...
kBool | kObject_Equals (kObject object, kObject other)
| Determines whether the object is equal to another object. More...
kSize | kObject_HashCode (kObject object)
| Gets a hash code representing the state of this object. More...
kBool | kObject_Is (kObject object, kType type)
| Determines whether this object is an instance of the specified type. More...
kBool | kObject_IsShared (kObject object)
| Reports whether the object is currently shared (reference count greater than one). More...
kStatus | kObject_SetPool (kObject object, kObjectPool pool)
| Sets the object pool associated with this object. More...
kStatus | kObject_Share (kObject object)
| Increments the reference count associated with this object. More...
kSize | kObject_Size (kObject object)
| Estimates the memory consumed by this object, including any aggregated child elements. More...
kType | kObject_Type (kObject object)
| Returns the type of the object. More...

## Additional Inherited Members
Related inherited from kObject
#define | kObject_Type_(OBJ) kxObject_Type_(OBJ)
| Macro version of kObject_Type.
#define | kObject_Is_(OBJ, TYPE) kxObject_Is_(OBJ, TYPE)
| Macro version of kObject_Is.
#define | kObject_Alloc_(OBJ) kxObject_Allocator_(OBJ)
| Macro version of kObject_Alloc.

The documentation for this class was generated from the following file:

- Threads/kMsgQueue.h