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

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

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

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

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

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

1. Создание абстракции очереди.

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

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

2. Обмен данными между потоками исполнения через добавление и извлечение элементов очереди.

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

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

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

   Чтобы очистить очередь и отменить резервирование всех зарезервированных участков в буфере очереди, нужно вызвать функцию KosQueueFlush().

3. Удаление абстракции очереди.

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

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

Функции queue.h