Использование пула памяти (mempool.h)

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

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

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

Создание пула

Чтобы создать пул, нужно вызвать функцию KosMempoolCreate() или KosMempoolCreateEx(). Через параметры blockCount и blockSize эти функции принимают число и размер блоков памяти соответственно.

Функция KosMempoolCreateEx() имеет дополнительные параметры.

В параметре flags нужно указать флаги, задающие параметры для операции получения блока памяти из пула при его опустошении. Для этого требуется передать функции структуру со следующими полями:

• usePreallocatedOnly – задает, нужно ли выделять блок памяти (rtl_false – да, rtl_true – нет).
• allowWaiting – задает, нужно ли ожидать возврата блока памяти в пул или освобождения блока памяти (rtl_true – да, rtl_false – нет).

Если пул пуст, то возможны следующие варианты выполнения операции получения блока памяти из пула:

• Если параметры usePreallocatedOnly и allowWaiting имеют значение rtl_false, то выполняется попытка выделить блок памяти. Если это не удается, то операция завершается с ошибкой.
• Если параметры usePreallocatedOnly и allowWaiting имеют значение rtl_true, то операция ожидает возврата блока памяти в пул, и поток исполнения, выполняющий операцию, блокируется.
• Если параметр usePreallocatedOnly имеет значение rtl_false, а параметр allowWaiting имеет значение rtl_true, то выполняется попытка выделить блок памяти. Если это не удается, то операция ожидает любого из событий: возврата блока памяти в пул или освобождения блока памяти, и поток исполнения, выполняющий операцию, блокируется.
• Если параметр usePreallocatedOnly имеет значение rtl_true, а параметр allowWaiting имеет значение rtl_false, то операция завершается с ошибкой.

Через параметры allocFunc, freeFunc и sanFunc можно задать callback-функции, вызываемые для выделения, освобождения и очистки блока памяти соответственно. Callback-функции выделения и освобождения блока памяти вызываются при создании и удалении пула. Также эти callback-функции опционально вызываются при выполнении операций получения блока памяти из пула и возврата блока памяти в пул. Callback-функция очистки блока памяти вызывается при выполнении операции возврата блока памяти в пул, чтобы, например, удалить содержимое этого блока. По умолчанию для выделения и освобождения блока памяти используются функции KosMemAlloc() и KosMemFree() соответственно (API alloc.h). Вместо callback-функций выделения и освобождения блока памяти можно задать, например, callback-функции создания и удаления какого-либо объекта.

Callback-функции выделения, освобождения и очистки блока памяти имеют входной параметр ctx, через который принимают указатель на произвольные данные, переданные функции KosMempoolCreateEx() через одноименный параметр. Callback-функции выделения и очистки блока памяти принимают размер блока памяти в байтах (входной параметр size), который задается через параметр blockSize функций KosMempoolCreate(Ex)(). Callback-функции освобождения и очистки блока памяти принимают указатель на блок памяти (входной параметр ptr).

Callback-функция выделения блока памяти в случае успеха возвращает указатель на блок памяти, иначе возвращает RTL_NULL. Callback-функции освобождения и очистки блока памяти не возвращают значений.

Идентичные вызовы функций KosMempoolCreate() и KosMempoolCreateEx():

KosMempoolCreate(blockCount, size);

KosMempoolCreateEx(blockCount, size, (KosMempoolFlags){0}, RTL_NULL, RTL_NULL, RTL_NULL, RTL_NULL);

Получение блока памяти из пула

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

Возврат блока памяти в пул

Чтобы вернуть блок памяти в пул, нужно вызвать функцию KosMempoolPut(). Если пул полностью заполнен, возвращаемый блок памяти будет освобожден.

Получение сведений о пуле

Чтобы получить размер блока памяти в пуле, нужно вызвать функцию KosMempoolGetBlockSize().

Чтобы получить данные, которые передаются callback-функциям выделения, освобождения и очистки блока памяти, нужно вызвать функцию KosMempoolGetContext().

Удаление пула

Чтобы удалить пул, нужно вызвать функцию KosMempoolDestroy().

Блоки памяти, которые не возвращены в пул (в том числе выделенные после создания пула), не будут освобождены.

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

Функции mempool.h