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()
{
    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