Função RtlInitializeGenericTableAvl (ntddk.h)

Artigo
02/07/2025

A rotina de rtlInitializeGenericTableAvl inicializa uma tabela genérica usando árvores Desassocupadas/Landis (AVL).

Sintaxe

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
);

Parâmetros

[out] Table

Um ponteiro para um buffer alocado por chamador, que deve ter pelo menos tamanhos de(RTL_AVL_TABLE) bytes de tamanho, para conter a estrutura de tabela genérica inicializada.

[in] CompareRoutine

Um ponto de entrada de uma rotina de retorno de chamada de comparação, declarado da seguinte maneira:

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

Os parâmetros de CompareRoutine são os seguintes:

Tabela (CompareRoutine)

Um ponteiro para a tabela genérica.

FirstStruct

Um ponteiro para o primeiro item a ser comparado.

SecondStruct

Um ponteiro para o segundo item a ser comparado.

O CompareRoutine deve acompanhar estritamente a ordenação de todos os elementos na tabela genérica para que possa identificar qualquer elemento específico. A estrutura definida pelo chamador para dados de elemento geralmente inclui um membro cujo valor é exclusivo e pode ser usado como uma chave de classificação. Todos Rtl... As rotinas de GenericTableAvl que chamam a CompareRoutine assumem um ponteiro de buffer como um parâmetro, que é passado por sua vez para a compareroutina de. O buffer contém um valor de chave fornecido pelo chamador a ser correspondido pelo CompareRoutine com a chave do elemento que está sendo pesquisado.

Considerando dois desses valores principais, o CompareRoutine retorna GenericLessThan, GenericGreaterThan ou GenericEqual.

[in] AllocateRoutine

Um ponto de entrada de uma rotina de retorno de chamada de alocação, declarado da seguinte maneira:

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

Os parâmetros AllocateRoutine são os seguintes:

Tabela (AllocateRoutine)

Um ponteiro para a tabela genérica.

ByteSize

O número de bytes a serem alocados.

Para cada novo elemento, o AllocateRoutine é chamado para alocar memória para dados fornecidos pelo chamador, além de alguma memória adicional para uso pelo Rtl... Rotinas de GenericTableAvl. Observe que, devido a essa "memória adicional", as rotinas fornecidas pelo chamador não devem acessar os primeiros tamanhos de(RTL_BALANCED_LINKS) bytes de qualquer elemento na tabela genérica.

[in] FreeRoutine

Um ponto de entrada de uma rotina de retorno de chamada de desalocação, declarado da seguinte maneira:

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

Os parâmetros de do FreeRoutine são os seguintes:

Tabela (FreeRoutine)

Um ponteiro para a tabela genérica.

Buffer

Um ponteiro para o elemento que está sendo excluído.

Rtl... As rotinas de GenericTableAvl chamam a freeroutine para desalocar a memória para que os elementos sejam excluídos da tabela genérica. O FreeRoutine é o oposto do AllocateRoutine.

[in, optional] TableContext

Um ponteiro opcional para um contexto fornecido pelo chamador para a tabela genérica. Esse parâmetro pode ser NULL.

Valor de retorno

Nenhum

Observações

Os sistemas de arquivos chamam RtlInitializeGenericTableAvl para inicializar uma tabela genérica para armazenar dados específicos do sistema de arquivos, como informações de pesquisa de nome para arquivos abertos no momento. A ordem de classificação, a estrutura e o conteúdo dos elementos são definidos pelo chamador.

Os sistemas de arquivos devem chamar rtlInitializeGenericTableAvl para inicializar a tabela genérica antes de usar qualquer outra Rtl... GenericTableAvl rotinas na nova tabela genérica. A estrutura de tabela genérica inicializada deve ser considerada opaca.

Chamadores do Rtl... As rotinas de GenericTableAvl são responsáveis por sincronizar exclusivamente o acesso à tabela genérica. Um mutex rápido exclusivo é o mecanismo de sincronização mais eficiente a ser usado para essa finalidade.

O CompareRoutine fornecido pelo chamador é chamado antes do AllocateRoutine para localizar um local apropriado no qual um novo elemento deve ser inserido. O CompareRoutine também é chamado antes do de FreeRoutine para localizar um elemento a ser excluído.

A rotina RtlInitializeGenericTableAvl aloca explicitamente uma tabela genérica que usa árvores AVL. Uso dessa rotina e das outras Rtl... As rotinas de GenericTableAvl são necessárias quando as tabelas baseadas em árvore AVL são desejadas e RTL_USE_AVL_TABLES não é definida antes de incluir Ntddk.h.

Se você quiser configurar as rotinas de tabela genéricas, Rtl... GenericTable, para usar árvores AVL em vez de árvores de reprodução no driver, insira a seguinte instrução de definição em um arquivo de cabeçalho comum antes de incluir Ntddk.h:

`#define RTL_USE_AVL_TABLES 0`

Os chamadores de RtlInitializeGenericTableAvl devem estar em execução no <DO IRQL = DISPATCH_LEVEL. Observe que se Rtl... As rotinas de GenericTableAvl devem ser usadas no IRQL DISPATCH_LEVEL, os deCompareRoutine, AllocateRoutinee freeroutine devem ser todos código não pagável e o AllocateRoutine deve alocar memória do pool nãopagado.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
cabeçalho	ntddk.h (incluem Ntddk.h, Ntifs.h, Fltkernel.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (consulte a seção Comentários)