Функция RtlInitializeGenericTableAvl (ntddk.h)

Статья
02/26/2024

Подпрограмма RtlInitializeGenericTableAvl инициализирует универсальную таблицу с помощью деревьев Adelson-Velsky/Landis (AVL).

Синтаксис

NTSYSAPI VOID RtlInitializeGenericTableAvl(
  [out]          PRTL_AVL_TABLE            Table,
  [in]           PRTL_AVL_COMPARE_ROUTINE  CompareRoutine,
  [in]           PRTL_AVL_ALLOCATE_ROUTINE AllocateRoutine,
  [in]           PRTL_AVL_FREE_ROUTINE     FreeRoutine,
  [in, optional] PVOID                     TableContext
);

Параметры

[out] Table

Указатель на буфер, выделенный вызывающим объектом, который должен иметь размер не менееRTL_AVL_TABLE байт, чтобы содержать инициализированную структуру универсальной таблицы.

[in] CompareRoutine

Точка входа подпрограммы обратного вызова сравнения, объявленная следующим образом:

RTL_GENERIC_COMPARE_RESULTS
(*PRTL_AVL_COMPARE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  FirstStruct,
    __in PVOID  SecondStruct
    );

Ниже перечислены параметры CompareRoutine .

Table (CompareRoutine)

Указатель на универсальную таблицу.

FirstStruct

Указатель на первый сравниваемый элемент.

SecondStruct

Указатель на второй сравниваемый элемент.

CompareRoutine должен строго отслеживать порядок всех элементов в универсальной таблице, чтобы он смог идентифицировать любой конкретный элемент. Определяемая вызывающим элементом структура для данных элемента обычно включает элемент, значение которого является уникальным и может использоваться в качестве ключа сортировки. Все Rtl... Подпрограммы GenericTableAvl , вызывающие CompareRoutine , принимают указатель буфера в качестве параметра, который, в свою очередь, передается в CompareRoutine. Буфер содержит значение ключа, предоставленное вызывающим объектом, которое будет сопоставляться compareRoutine с ключом искомого элемента.

При двух таких значениях ключей CompareRoutine возвращает GenericLessThan, GenericGreaterThan или GenericEqual.

[in] AllocateRoutine

Точка входа подпрограммы обратного вызова выделения, объявленная следующим образом:

PVOID
(*PRTL_AVL_ALLOCATE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in CLONG  ByteSize
    );

Ниже перечислены параметры AllocateRoutine .

Таблица (AllocateRoutine)

Указатель на универсальную таблицу.

ByteSize

Количество байтов, которые необходимо выделить.

Для каждого нового элемента метод AllocateRoutine вызывается для выделения памяти для данных, предоставленных вызывающим, а также некоторой дополнительной памяти для использования rtl... Подпрограммы GenericTableAvl . Обратите внимание, что из-за этой "дополнительной памяти" подпрограммы, предоставляемые вызывающим абонентом, не должны обращаться к первым байтам sizeof(RTL_BALANCED_LINKS) любого элемента в универсальной таблице.

[in] FreeRoutine

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

VOID
(*PRTL_AVL_FREE_ROUTINE) (
    __in struct _RTL_AVL_TABLE  *Table,
    __in PVOID  Buffer
    );

Ниже перечислены параметры FreeRoutine .

Таблица (FreeRoutine)

Указатель на универсальную таблицу.

Буфер

Указатель на удаляемый элемент.

Rtl... Подпрограммы GenericTableAvl вызывают FreeRoutine , чтобы освободить память для элементов, которые будут удалены из универсальной таблицы. FreeRoutine является противоположностью AllocateRoutine.

[in, optional] TableContext

Необязательный указатель на контекст, предоставленный вызывающим объектом, для универсальной таблицы. Этот параметр может принимать значение NULL.

Возвращаемое значение

None

Remarks

Файловые системы вызывают RtlInitializeGenericTableAvl для инициализации универсальной таблицы для хранения данных, относящихся к файловой системе, таких как сведения о поиске имен для открытых файлов. Порядок сортировки, структура и содержимое элементов определяются вызывающим.

Файловые системы должны вызывать RtlInitializeGenericTableAvl для инициализации универсальной таблицы перед использованием любого другого Rtl... Подпрограммы GenericTableAvl в новой универсальной таблице. Инициализированную структуру универсальной таблицы следует считать непрозрачной.

Абоненты Rtl... Подпрограммы GenericTableAvl отвечают за исключительно синхронизацию доступа к универсальной таблице. Эксклюзивный быстрый мьютекс является наиболее эффективным механизмом синхронизации для этой цели.

Предоставленный вызывающим элемент CompareRoutine вызывается перед AllocateRoutine , чтобы найти подходящее расположение, в которое следует вставить новый элемент. CompareRoutine также вызывается перед FreeRoutine, чтобы найти удаляемый элемент.

Подпрограмма RtlInitializeGenericTableAvl явным образом выделяет универсальную таблицу, которая использует деревья AVL. Использование этой процедуры и других Rtl... Подпрограммы GenericTableAvl необходимы, если нужны таблицы на основе дерева AVL и RTL_USE_AVL_TABLES не определен перед включением ntddk.h.

Если вы хотите настроить подпрограммы универсальной таблицы, rtl... GenericTable, чтобы использовать деревья AVL вместо деревьев splay в драйвере, вставьте следующую инструкцию define в общий файл заголовка перед включением ntddk.h:

`#define RTL_USE_AVL_TABLES 0`

Вызывающие операторы RtlInitializeGenericTableAvl должны выполняться по адресу IRQL <= DISPATCH_LEVEL. Обратите внимание, что если Rtl... Подпрограммы GenericTableAvl должны использоваться на DISPATCH_LEVEL IRQL. Все функции CompareRoutine, AllocateRoutine и FreeRoutine должны быть непередаваемым кодом, а Свойство AllocateRoutine должно выделять память из пула без паг.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntddk.h (включая Ntddk.h, Ntifs.h, Fltkernel.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (см. раздел "Примечания")