Использование очередей (queue.h)

API определен в заголовочном файле sysroot-*-kos/include/kos/queue.h из состава KasperskyOS SDK.

API позволяет организовать обмен данными между потоками исполнения, принадлежащими одному процессу, через механизм очередей без блокировок. То есть для добавления или извлечения элементов очереди не требуется блокирование других потоков исполнения, добавляющих или извлекающих элементы этой очереди.

Сведения о функциях API приведены в таблице ниже.

Использование API

Типовой сценарий использования API включает следующие шаги:

Создание абстракции очереди.
Абстракция очереди состоит из структуры, содержащей метаданные об очереди, и буфера очереди, предназначенного для хранения элементов очереди. Буфер очереди логически разделен на равные участки, каждый из которых предназначен для отдельного элемента очереди. Число участков в буфере очереди соответствует максимальному числу элементов в очереди. Выравнивание адресов участков соответствует типам данных элементов очереди.

Чтобы выполнить этот шаг, нужно вызвать функцию KosQueueCreate(). Эта функция может выделить память для буфера очереди или использовать уже выделенную память. Размер уже выделенной памяти должен быть достаточным, чтобы вместить максимальное число элементов в очереди. При этом нужно учитывать, что размер участка в буфере очереди округляется до ближайшего большего кратного значению выравнивания, заданному через параметр objAlign. Также начальный адрес уже выделенной памяти должен быть выравнен так, чтобы соответствовать типам данных элементов очереди. Если выравнивание адреса памяти, указанного в параметре buffer, меньше заданного через параметр objAlign, то функция вернет RTL_NULL.
Обмен данными между потоками исполнения через добавление и извлечение элементов очереди.
Чтобы добавить один элемент в конец очереди, нужно зарезервировать участок в буфере очереди вызовом функции KosQueueAlloc(), скопировать этот элемент в зарезервированный участок и вызвать функцию KosQueuePush().

Чтобы добавить последовательность элементов в конец очереди, нужно зарезервировать требуемое количество участков в буфере очереди вызовами функции KosQueueAlloc(), скопировать элементы этой последовательности в зарезервированные участки и вызвать функцию KosQueuePushArray(). Порядок элементов последовательности не изменяется после добавления этой последовательности в очередь. То есть элементы добавляются очередь в том же порядке, в каком указатели на зарезервированные участки в буфере очереди помещены в массив, передаваемый через параметр objs функции KosQueuePushArray().

Чтобы извлечь первый элемент очереди, нужно вызвать функцию KosQueuePop(). Эта функция возвращает указатель на зарезервированный участок в буфере очереди, который содержит первый элемент очереди. После использования извлеченного элемента (например, после проверки или сохранения значения элемента) нужно отменить резервирование занятого этим элементом участка в буфере очереди. Для этого нужно вызвать функцию KosQueueFree().

Чтобы очистить очередь и отменить резервирование всех зарезервированных участков в буфере очереди, нужно вызвать функцию KosQueueFlush().
Удаление абстракции очереди.
Чтобы выполнить этот шаг, нужно вызвать функцию KosQueueDestroy(). Эта функция удаляет буфер очереди, если только память для этого буфера была выделена функцией KosQueueCreate(). В противном случае нужно отдельно выполнить удаление буфера очереди.

Сведения о функциях API

Функции queue.h

Функция	Сведения о функции
`KosQueueCreate()`	Назначение Создает абстракцию очереди. Параметры [in] `objCount` – максимальное число элементов в очереди. [in] `objSize` – размер элемента очереди в байтах. [in] `objAlign` – выравнивание адресов участков в буфере очереди. Адреса участков в буфере очереди могут быть невыравненными (objAlign=1) или выравненными (objAlign=2,4,...,2^N) на границу 2^N-байтовой последовательности (например, двухбайтовой, четырехбайтовой). [in,optional] `buffer` – указатель на выделенную память для буфера очереди или `RTL_NULL`, чтобы память была выделена автоматически. Возвращаемые значения В случае успеха возвращает идентификатор абстракции очереди, иначе возвращает `RTL_NULL`.
`KosQueueDestroy()`	Назначение Удаляет абстракцию очереди. Параметры [in] `queue` – идентификатор абстракции очереди. Возвращаемые значения Нет.
`KosQueueAlloc()`	Назначение Резервирует участок в буфере очереди. Параметры [in] `queue` – идентификатор абстракции очереди. Возвращаемые значения В случае успеха возвращает указатель на зарезервированный участок в буфере очереди, иначе возвращает `RTL_NULL`.
`KosQueueFree()`	Назначение Отменяет резервирование заданного участка в буфере очереди. Параметры [in] `queue` – идентификатор абстракции очереди. [in] `obj` – указатель на зарезервированный участок в буфере очереди. Возвращаемые значения Нет.
`KosQueuePush()`	Назначение Добавляет элемент в конец очереди. Параметры [in] `queue` – идентификатор абстракции очереди. [in] `obj` – указатель на зарезервированный участок в буфере очереди. Возвращаемые значения Нет.
`KosQueuePushArray()`	Назначение Добавляет последовательность элементов в конец очереди. Параметры [in] `queue` – идентификатор абстракции очереди. [in] `objs` – массив указателей на зарезервированные участки в буфере очереди. [in] `count` – число элементов в последовательности. Возвращаемые значения Нет.
`KosQueuePop()`	Назначение Извлекает первый элемент очереди. Параметры [in] `queue` – идентификатор абстракции очереди. [in] `timeout` – время ожидания появления элемента в очереди в миллисекундах или `INFINITE_TIMEOUT`, чтобы задать неограниченное время ожидания. Возвращаемые значения В случае успеха возвращает указатель на зарезервированный участок в буфере очереди, который содержит первый элемент очереди. Иначе возвращает `RTL_NULL`.
`KosQueueFlush()`	Назначение Очищает очередь и отменяет резервирование всех зарезервированных участков в буфере очереди. Параметры [in] `queue` – идентификатор абстракции очереди. Возвращаемые значения Нет.

В начало