Zen API
 All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
kMsgQueue Class Reference

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()
{
kThread thread = kNULL;
kObject quitMsg = kNULL;
kSize i;
{
//create a queue that can store images
//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));
}
{
//destroying the thread will join automatically
kObject_Destroy(thread);
//disposing the queue will also destroy any images remaining in the queue
kObject_Dispose(queue);
}
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:
Inheritance graph

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...
 
kBool kObject_HasForeignData (kObject object)
 Reports whether the object, including aggregated child elements, contains any foreign memory references. 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...
 

Related

#define kMsgQueue_AddExT(kMsgQueue_queue, TPtr_item, kMsgQueueItemOption_options)
 Adds an item to the queue with the specified options. More...
 
#define kMsgQueue_AddT(kMsgQueue_queue, TPtr_item)
 Adds an item to the queue. More...
 
#define kMsgQueue_RemoveT(kMsgQueue_queue, TPtr_item, k64u_timeout)
 Removes an item from the queue. More...
 

Additional Inherited Members

- Protected Member Functions inherited from kObject
kStatus kObject_FreeMem (kObject object, void *mem)
 Protected method called by derived classes to free memory using the object's allocator. More...
 
kStatus kObject_FreeMemRef (kObject object, void *mem)
 Protected method called by derived classes to free memory (and reset the provided memory pointer to kNULL) using the object's allocator. More...
 
kStatus kObject_GetMem (kObject object, kSize size, void *mem)
 Protected method called by derived classes to allocate memory using the object's allocator. More...
 
kStatus kObject_GetMemZero (kObject object, kSize size, void *mem)
 Protected method called by derived classes to allocate and zero memory using the object's allocator. More...
 
kStatus kObject_Init (kObject object, kType type, kAlloc alloc)
 Protected method called by derived classes to initialize the kObject base class. More...
 
kStatus kObject_VDisposeItems (kObject object)
 Protected virtual method that destroys any aggregated child objects associated with a collection. More...
 
kBool kObject_VEquals (kObject object, kObject other)
 Protected virtual method that compares two objects for equality. More...
 
kBool kObject_VHasForeignData (kObject object)
 Protected virtual method that reports whether the object, including aggregated child elements, contains any foreign memory references. More...
 
kSize kObject_VHashCode (kObject object)
 Protected virtual method that calculates a hash code representing the object instance. More...
 
kStatus kObject_VInitClone (kObject object, kObject source, kAlloc allocator)
 Protected virtual method that clones (makes a deep copy of) the specified source object. More...
 
kStatus kObject_VRelease (kObject object)
 Protected virtual method that deallocates any resources owned by the object. More...
 
kSize kObject_VSize (kObject object)
 Protected virtual method that calculates the total size (in bytes) of the object instance. More...
 

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