Using queues (queue.h)

The API is defined in the header file sysroot-*-kos/include/kos/queue.h from the KasperskyOS SDK.

The API sets up data exchange between threads owned by one process via a queuing mechanism that does not lock threads. In other words, you can add or extract elements of a queue without locking other threads that add or extract elements of this queue.

Information about API functions is provided in the table below.

Using the API

The standard scenario for API usage includes the following steps:

1. Create a queue abstraction.

   A queue abstraction consists of a structure containing queue metadata and a queue buffer intended for storing elements of the queue. A queue buffer is logically divided into equal segments, each of which is intended for an individual element of the queue. The number of segments in a queue buffer matches the maximum number of elements in the queue. The alignment of segment addresses corresponds to the data types of elements in the queue.

   To complete this step, call the KosQueueCreate() function. This function can allocate memory for the queue buffer or use already allocated memory. The size of the already allocated memory must be sufficient to accommodate the maximum number of elements in the queue. Also take into account that the size of a segment in the queue buffer is rounded to the next largest multiple of the alignment value defined through the objAlign parameter. The initial address of the already allocated memory must also be aligned to correspond to the data types of queue elements. If the memory address alignment specified in the buffer parameter is less than the value defined through the objAlign parameter, the function returns RTL_NULL.

2. Exchange data between threads by adding and extracting elements of the queue.

   To add one element to the end of the queue, you must reserve a segment in the queue buffer by calling the KosQueueAlloc() function, copy this element to the reserved segment, and call the KosQueuePush() function.

   To add a sequence of elements to the end of the queue, you must reserve the necessary number of segments in the queue buffer via KosQueueAlloc() function calls, copy the elements of this sequence to the reserved segments, and call the KosQueuePushArray() function. The order of elements in a sequence is not changed after this sequence is added to the queue. In other words, elements are added to the queue in the same order in which the pointers to reserved segments in the queue buffer are put into the array that is passed through the objs parameter of the KosQueuePushArray() function.

   To extract the first element of the queue, you must call the KosQueuePop() function. This function returns the pointer to the reserved segment in the queue buffer that contains the first element of the queue. After using an extracted element (for example, after checking or saving the value of an element), you must free the queue buffer segment occupied by this element. To do so, call the KosQueueFree() function.

   To clear the queue and free all registered segments in the queue buffer, you must call the KosQueueFlush() function.

3. Delete the queue abstraction.

   To complete this step, call the KosQueueDestroy() function. This function deletes the queue buffer if only the memory for this buffer was allocated by the KosQueueCreate() function. Otherwise, you must separately delete the queue buffer.

Information about API functions

queue.h functions

Function	Information about the function
KosQueueCreate()	Purpose Creates a queue abstraction. Parameters [in] objCount – maximum number of elements in the queue. [in] objSize – size (in bytes) of an element in the queue. [in] objAlign – alignment of segment addresses in the queue buffer. The addresses of segments in the queue buffer may be unaligned (objAlign=1) or aligned (objAlign=2,4,...,2^N) to the boundary of a 2^N-byte sequence (for example, two-byte or four-byte). [in,optional] buffer – pointer to the allocated memory for the queue buffer, or RTL_NULL to automatically allocate the memory. Returned values If successful, the function returns the queue abstraction ID, otherwise it returns RTL_NULL.
KosQueueDestroy()	Purpose Deletes a queue abstraction. Parameters [in] queue – queue abstraction ID. Returned values N/A
KosQueueAlloc()	Purpose Reserves a segment in the queue buffer. Parameters [in] queue – queue abstraction ID. Returned values If successful, the function returns the pointer to the reserved segment in the queue buffer, otherwise it returns RTL_NULL.
KosQueueFree()	Purpose Resets the reservation of the defined segment in the queue buffer. Parameters [in] queue – queue abstraction ID. [in] obj – pointer to the reserved segment in the queue buffer. Returned values N/A
KosQueuePush()	Purpose Adds an element to the end of the queue. Parameters [in] queue – queue abstraction ID. [in] obj – pointer to the reserved segment in the queue buffer. Returned values N/A
KosQueuePushArray()	Purpose Adds a sequence of elements to the end of the queue. Parameters [in] queue – queue abstraction ID. [in] objs – array of pointers to reserved segments in the queue buffer. [in] count – number of elements in the sequence. Returned values N/A
KosQueuePop()	Purpose Extracts the first element of the queue. Parameters [in] queue – queue abstraction ID. [in] timeout – timeout (in milliseconds) for an element to appear in the queue, or INFINITE_TIMEOUT to set an unlimited timeout. Returned values If successful, this function returns the pointer to the reserved segment in the queue buffer containing the first element of the queue. Otherwise it returns RTL_NULL.
KosQueueFlush()	Purpose Clears the queue and resets the reservation of all registered segments in the queue buffer. Parameters [in] queue – queue abstraction ID. Returned values N/A

Page top