RtlGetElementGenericTableAvl function (ntddk.h)

The RtlGetElementGenericTableAvl routine returns a pointer to the caller-supplied data for a particular generic Adelson-Velsky/Landis (AVL) table element.

Syntax

NTSYSAPI PVOID RtlGetElementGenericTableAvl(
  [in] PRTL_AVL_TABLE Table,
  [in] ULONG          I
);

Parameters

[in] Table

Pointer to the generic AVL table (RTL_AVL_TABLE) from which the Ith element is to be retrieved. The table must have been initialized by calling RtlInitializeGenericTableAvl.

[in] I

Index of the element selected. This value is zero-based, so the index of the last-inserted element currently in Table is always one less than the value returned by RtlNumberGenericTableElementsAvl.

Return value

RtlGetElementGenericTableAvl returns a pointer to the caller-supplied data for the Ith element in the generic AVL table. It returns NULL if the given I is too large or if the generic AVL table currently has no elements.

Remarks

RtlGetElementGenericTableAvl returns the Ith element inserted in the generic AVL table. To retrieve the first element, set I to zero. To retrieve the last element, set I to (RtlNumberGenericTableElementsAvl(Table)-1). Note that if an element is deleted from the generic table, the indexes of all elements inserted after the deleted element are decremented. Thus an element's index might change over time.

RtlGetElementGenericTableAvl is more efficient than RtlLookupElementGenericTableAvl if the caller can supply the index of a particular element for which the caller needs access to the associated data. However, calling RtlGetElementGenericTableAvl repeatedly to test for such an element is less efficient than calling RtlLookupElementGenericTableAvl to locate it.

Callers of the Rtl..GenericTable routines are responsible for exclusively synchronizing access to the generic table. An exclusive fast mutex is the most efficient synchronization mechanism to use for this purpose.

By default, the operating system uses splay trees to implement generic tables. Under some circumstances, operations on a splay tree will make the tree deep and narrow and might even turn it into a straight line. Very deep trees degrade the performance of searches. You can ensure a more balanced, shallower tree implementation of generic tables by using Adelson-Velsky/Landis (AVL) trees. If you want to configure the generic table routines to use AVL trees instead of splay trees in your driver, insert the following define statement in a common header file before including Ntddk.h:

#define RTL_USE_AVL_TABLES 0

If RTL_USE_AVL_TABLES is not defined, you must use the AVL form of the generic table routines. For example, use the RtlGetElementGenericTableAvl routine instead of RtlGetElementGenericTable. In the call to RtlGetElementGenericTableAvl, the caller must pass a RTL_AVL_TABLE table structure rather than RTL_GENERIC_TABLE.

Callers of RtlGetElementGenericTableAvl must be running at IRQL < DISPATCH_LEVEL if the caller-allocated memory for the generic table is pageable.

Requirements

See also

RtlDeleteElementGenericTableAvl

RtlEnumerateGenericTableWithoutSplayingAvl

RtlInitializeGenericTableAvl

RtlInsertElementGenericTableAvl

RtlLookupElementGenericTableAvl

RtlNumberGenericTableElementsAvl