RtlInitializeGenericTableAvl 函数 (ntddk.h)

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 参数如下所示:

表 (CompareRoutine)

指向泛型表的指针。

FirstStruct

指向要比较的第一项的指针。

SecondStruct

指向要比较的第二项的指针。

CompareRoutine 必须严格跟踪泛型表中所有元素的顺序,以便它可以标识任何特定元素。 元素数据的调用方定义的结构通常包括一个成员,其值是唯一的,可用作排序键。 所有 Rtl... 调用 CompareRoutine 的 GenericTableAvl 例程将缓冲区指针作为参数,该参数将依次传递给 CompareRoutine。 缓冲区包含调用方提供的键值, CompareRoutine 将与要搜索的元素的键进行匹配。

给定两个这样的键值, CompareRoutine 返回 GenericLessThanGenericGreaterThanGenericEqual

[in] AllocateRoutine

分配回调例程的入口点,声明如下:

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

AllocateRoutine 参数如下所示:

Table (AllocateRoutine)

指向泛型表的指针。

ByteSize

要分配的字节数。

对于每个新元素,调用 AllocateRoutine 来为调用方提供的数据分配内存,以及一些额外的内存供 Rtl...GenericTableAvl 例程。 请注意,由于这种“额外内存”,调用方提供的例程不得访问泛型表中任何元素的第一个 大小 (RTL_BALANCED_LINKS) 字节。

[in] FreeRoutine

解除分配回调例程的入口点,声明如下:

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

FreeRoutine 参数如下所示:

表 (FreeRoutine)

指向泛型表的指针。

Buffer

指向要删除的元素的指针。

Rtl。。。GenericTableAvl 例程调用 FreeRoutine 以解除分配要从泛型表中删除的元素的内存。 FreeRoutineAllocateRoutine 相反。

[in, optional] TableContext

指向泛型表的调用方提供的上下文的可选指针。 此参数可以为 NULL。

返回值

备注

文件系统调用 RtlInitializeGenericTableAvl 来初始化泛型表以存储文件系统特定的数据,例如当前打开的文件的名称查找信息。 元素的排序顺序、结构和内容由调用方定义。

文件系统必须调用 RtlInitializeGenericTableAvl 以初始化泛型表,然后才能使用任何其他 Rtl...新泛型表上的 GenericTableAvl 例程。 初始化的泛型表结构应被视为不透明。

Rtl 的调用方 ...GenericTableAvl 例程负责以独占方式同步对泛型表的访问。 排他快速互斥体是用于此目的的最有效同步机制。

调用方提供的 CompareRoutineAllocateRoutine 之前调用,以找到应插入新元素的适当位置。 在 FreeRoutine 之前,还会调用 CompareRoutine,以查找要删除的元素。

RtlInitializeGenericTableAvl 例程显式分配使用 AVL 树的泛型表。 使用此例程和其他 Rtl... 如果需要基于 AVL 树的表,并且未在包括 Ntddk.h 之前定义RTL_USE_AVL_TABLES,则必须使用 GenericTableAvl 例程。

如果要配置泛型表例程, 则 Rtl...GenericTable 若要在驱动程序中使用 AVL 树而不是 splay 树,请在包含 Ntddk.h 之前在通用头文件中插入以下 define 语句:

`#define RTL_USE_AVL_TABLES 0`

RtlInitializeGenericTableAvl 的调用方必须在 IRQL <= DISPATCH_LEVEL 运行。 请注意,如果 Rtl...GenericTableAvl 例程要在 IRQL DISPATCH_LEVEL中使用, CompareRoutineAllocateRoutineFreeRoutine 都必须是不可分页的代码,并且 AllocateRoutine 应从非分页池分配内存。

要求

要求
目标平台 通用
标头 ntddk.h (包括 Ntddk.h、Ntifs.h、Fltkernel.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (请参阅备注部分)

另请参阅

ExInitializeFastMutex

RtlDeleteElementGenericTableAvl

RtlEnumerateGenericTableAvl

RtlGetElementGenericTableAvl

RtlInitializeGenericTable

RtlInsertElementGenericTableAvl

RtlLookupElementGenericTableAvl

RtlNumberGenericTableElementsAvl