ExInitializeLookasideListEx 関数 (wdm.h)

[アーティクル]
06/08/2023

ExInitializeLookasideListEx ルーチンは、ルックアサイドリストを初期化します。

構文

NTSTATUS ExInitializeLookasideListEx(
  [out]          PLOOKASIDE_LIST_EX    Lookaside,
  [in, optional] PALLOCATE_FUNCTION_EX Allocate,
  [in, optional] PFREE_FUNCTION_EX     Free,
  [in]           POOL_TYPE             PoolType,
  [in]           ULONG                 Flags,
  [in]           SIZE_T                Size,
  [in]           ULONG                 Tag,
  [in]           USHORT                Depth
);

パラメーター

[out] Lookaside

初期化する LOOKASIDE_LIST_EX 構造体へのポインター。返された場合、この構造体は空のルックアサイドリストを記述します。呼び出し元は、ルックアサイド・リスト内の項目がページ・メモリーまたは非ページ・メモリーから割り振られているかどうかに関係なく、この構造体に非ページ・システム・スペースを使用する必要があります。 64 ビットプラットフォームでは、この構造体は 16 バイトアラインされている必要があります。

[in, optional] Allocate

新しい lookaside-list エントリを割り当てる、呼び出し元が指定した LookasideListAllocateEx ルーチンへのポインター。 ExAllocateFromLookasideListEx ルーチンは、ルックアサイドリストが空の場合 (エントリが含まれない) 場合に、この LookasideListAllocateEx ルーチンを呼び出します。このパラメーターは省略可能であり、カスタム割り当てルーチンが必要ない場合は NULL として指定できます。このパラメーターが NULL の場合、 ExAllocateFromPagedLookasideList を呼び出すと、( PoolType パラメーターによって決定される) ページまたは非ページストレージが新しいエントリに自動的に割り当てられます。

[in, optional] Free

以前に割り当てられた lookaside-list エントリを解放する、呼び出し元から提供された LookasideListFreeEx ルーチンへのポインター。 ExFreeToPagedLookasideList ルーチンは、ルックアサイドリストがいっぱいの場合に、この LookasideListFreeEx ルーチンを呼び出します (つまり、オペレーティングシステムによって決定されるエントリの最大数がリストに既に含まれています)。このパラメーターは省略可能であり、カスタム割り当て解除ルーチンが必要ない場合は NULL として指定できます。このパラメーターが NULL の場合、 ExFreeToPagedLookasideList を呼び出すと、指定されたエントリのストレージが自動的に解放されます。

[in] PoolType

ルックアサイドリスト内のエントリのプールの種類を指定します。このパラメーターを有効なPOOL_TYPE列挙値に設定します。

[in] Flags

LookasideListAllocateEx ルーチンの既定の動作を変更する省略可能なフラグ値を指定します。このパラメーターを 0 に設定するか、次のいずれかのEX_LOOKASIDE_LIST_EX_FLAGS_XXX フラグビットに設定します。

フラグビット	説明
EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL	割り当てが失敗した場合は、例外を発生させます。
EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE	割り当てが失敗した場合は、例外を発生させる代わりに NULL を返します。このフラグは、プールの使用にクォータを課金する割り当てルーチン ( ExAllocatePoolWithQuotaTag など) で使用することを目的としています。

これら 2 つのフラグビットは相互に排他的です。

Allocate が NULL の場合は、フラグを 0 またはEX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAILに設定しますが、EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISEには設定しません。それ以外の場合、既定の割り当てルーチンの動作は未定義です。

Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAILの場合、PoolType パラメーター値は、LookasideListAllocateEx ルーチンに渡される PoolType パラメーター値を形成するために、POOL_RAISE_IF_ALLOCATION_FAILURE フラグビットを持つビットごとの ORed になります。 LookasideListAllocateEx ルーチンは、変更せずにこの PoolType 値を ExAllocatePoolWithTag ルーチンに渡すことができます。 POOL_RAISE_IF_ALLOCATION_FAILURE フラグの詳細については、「 ExAllocatePoolWithTag」を参照してください。

Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISEの場合、PoolType パラメーター値はビットごとの ORed で、POOL_QUOTA_FAIL_INSTEAD_OF_RAISE フラグビットを使用して、LookasideListAllocateEx ルーチンに渡される PoolType パラメーター値を形成します。 LookasideListAllocateEx ルーチンは、変更せずにこの PoolType 値を ExAllocatePoolWithQuotaTag ルーチンに渡すことができます。 POOL_QUOTA_FAIL_INSTEAD_OF_RAISE フラグの詳細については、「 ExAllocatePoolWithQuotaTag」を参照してください。

[in] Size

ルックアサイドリスト内の各エントリのサイズをバイト単位で指定します。

[in] Tag

割り当てられたストレージをルックアサイド・リスト項目にマークするために使用する 4 バイト・プール・タグを指定します。プールタグの詳細については、ExAllocatePoolWithTag の Tag パラメーターの説明を参照してください。

[in] Depth

予約済み。常に、このパラメーターを 0 に設定します。

戻り値

呼び出しが成功した場合、ExInitializeLookasideListEx はSTATUS_SUCCESSを返します。可能な戻り値には、次のエラーコードが含まれます。

リターンコード	説明
STATUS_INVALID_PARAMETER_4	PoolType パラメーター値が無効です。
STATUS_INVALID_PARAMETER_5	Flags パラメーターの値が無効です。

注釈

ドライバーは、リストの使用を開始する前に、ルックアサイドリストを初期化するには、このルーチンを呼び出す必要があります。ルックアサイドリストは、ドライバーがローカルで管理してシステム割り当てルーチンの呼び出しの数を減らし、それによってパフォーマンスを向上させることができる固定サイズのバッファーのプールです。バッファーは、ルックアサイドリストにエントリとして格納されます。リスト内のすべてのエントリは、 Size パラメーターで指定された同じ均一サイズです。

ExInitializeLookasideListEx が返されると、ルックアサイドリストは初期化されますが、エントリは含まれます。クライアントが ExAllocateFromLookasideListEx ルーチンを呼び出してエントリを要求すると、このルーチンはルックアサイドリストが空であると判断し、ドライバーが提供する LookasideListAllocateEx ルーチンを呼び出して、新しいエントリの記憶域を動的に割り当てます。クライアントからの同様の要求に応じて、追加のエントリが割り当てられる場合があります。その後、クライアントが ExFreeToLookasideListEx を呼び出してこれらのエントリを解放すると、このルーチンによって、そのエントリがルックアサイドリストに挿入されます。リスト内のエントリの数がオペレーティングシステムによって決定される制限に達した場合、 ExFreeToLookasideListEx はリストへのエントリの追加を停止し、代わりにこれらのエントリをドライバーが提供する LookasideListFreeEx ルーチンに渡して解放します。

ドライバーで LookasideListAllocateEx ルーチンと LookasideListFreeEx ルーチンが指定されていない場合、 ExAllocateFromLookasideListEx ルーチンと ExFreeToLookasideListEx ルーチンでは、代わりに既定の割り当てルーチンと割り当て解除ルーチンが使用されます。

ExAllocatePoolWithTag と ExFreePool を呼び出す以外に何もしない LookasideListAllocateEx ルーチンと LookasideListFreeEx ルーチンを提供してもメリットはありません。 Allocate パラメーターと Free パラメーターを NULL に設定するだけで、パフォーマンスを向上させることで、同じ効果を実現できます。

ドライバーをアンロードする前に、作成したルックアサイドリストを明示的に解放する必要があります。これを行わないと、重大なプログラミングエラーになります。 ExDeleteLookasideListEx ルーチンを呼び出して、ルックアサイドリストを解放します。このルーチンは、指定されたルックアサイドリスト内の残りのエントリのストレージを解放し、システム全体のアクティブなルックアサイドリストのセットからリストを削除します。

オペレーティングシステムは、現在使用されているすべてのルックアサイドリストを追跡します。使用可能な非ページメモリの量とルックアサイドリストエントリの需要の両方が時間の経過と共に異なるため、オペレーティングシステムは、非ページルックアサイドリストのエントリの最大数に対する制限を動的に調整します。

Windows 2000 以降のバージョンの Windows では、ページまたは非ページエントリを含むルックアサイドリストは、それぞれ PAGED_LOOKASIDE_LIST または NPAGED_LOOKASIDE_LIST 構造で記述できます。

ルックアサイドリストの詳細については、「Lookaside Listsの使用」を参照してください。

ExInitializeLookasideListEx の呼び出し元は IRQL <= DISPATCH_LEVELで実行できますが、通常は IRQL = PASSIVE_LEVELで実行されます。

例

ドライバー提供の LookasideListAllocateEx ルーチンと LookasideListFreeEx ルーチンはどちらも、ルックアサイドリストを記述するLOOKASIDE_LIST_EX構造体を指す Lookaside パラメーターを受け取ります。ルーチンは、このパラメーターを使用して、ドライバーがルックアサイドリストに関連付けたプライベートデータにアクセスできます。たとえば、ドライバーは、作成するルックアサイドリストごとにプライベートデータを収集するために、次の構造体のインスタンスを割り当てる場合があります。

typedef struct
{
  ULONG NumberOfAllocations;  // number of entries allocated
  ULONG NumberOfFrees;        // number of entries freed
  LOOKASIDE_LIST_EX LookasideField;
} MY_PRIVATE_DATA;

ドライバーは、次のコード例に示すように、ルックアサイドリストを初期化できます。

#define ENTRY_SIZE  256
#define MY_POOL_TAG  'tsLL'      
MY_PRIVATE_DATA *MyContext;
NTSTATUS status = STATUS_SUCCESS;
 
MyContext = ExAllocatePoolWithTag(NonPagedPool, sizeof(MY_PRIVATE_DATA), MY_POOL_TAG);
if (MyContext)
{
    MyContext.NumberOfAllocations = 0;
    MyContext.NumberOfFrees = 0;

    status = ExInitializeLookasideListEx(
                 &MyContext.LookasideField,
                 MyLookasideListAllocateEx,
                 MyLookasideListFreeEx,
                 NonPagedPool,
                 0,
                 ENTRY_SIZE,
                 MY_POOL_TAG,
                 0);
}
else
{
    status = STATUS_INSUFFICIENT_RESOURCES;
}

次のコード例は、 LookasideListAllocateEx ルーチンが Lookaside パラメーターを使用して、ルックアサイドリストに関連付けられているプライベートデータにアクセスする方法を示しています。

PVOID
  MyLookasideListAllocateEx(
    __in POOL_TYPE  PoolType,
    __in SIZE_T  NumberOfBytes,
    __in ULONG  Tag,
    __inout PLOOKASIDE_LIST_EX  Lookaside)
{
    MY_PRIVATE_DATA *MyContext;
    PVOID NewEntry;

    MyContext = CONTAINING_RECORD(Lookaside, MY_PRIVATE_DATA, LookasideField);

    NewEntry = ExAllocatePoolWithTag(PoolType, NumberOfBytes, Tag);

    if (NewEntry)
    {
        ULONG NumberOfAllocations = (ULONG) InterlockedIncrement((LONG volatile*)&MyContext->NumberOfAllocations);
    }

    return NewEntry;
}

CONTAINING_RECORD マクロは Ntdef.h ヘッダーファイルで定義されています。 LookAsideListFreeEx ルーチンも同様に、Lookaside パラメーターを使用してプライベートデータにアクセスできます。

この例の MyLookasideListAllocateEx ルーチンが戻った後、 ExAllocateFromLookasideListEx はNewEntry 変数が指すバッファーをルックアサイドリストに挿入します。この挿入操作をスレッドセーフにするために、 ExAllocateFromLookasideListEx は 、ルックアサイドリストへのアクセスを、他のスレッドによって実行される可能性のある他のリストの挿入および削除操作と同期します。同様に、 ExFreeFromLookasideListEx がルックアサイドリストからバッファーを削除すると、リストへのアクセスが同期されます。

ExAllocateFromLookasideListEx および ExFreeFromLookasideListEx は、ドライバーが提供する LookasideListAllocateEx ルーチンおよび LookasideListFreeEx ルーチンへの呼び出しを同期しません。したがって、前のコード例の MyLookasideListAllocateEx ルーチンと MyLookasideListFreeEx ルーチンがスレッドセーフである必要がある場合、ドライバーは必要な同期を提供する必要があります。

このサンプルルーチン MyLookasideListAllocateEx は、MyContext-NumberOfAllocations> 変数へのアクセスを、この変数をインクリメントおよびデクリメントする可能性のある他のスレッドと同期します。この同期を提供するために、 MyLookasideListAllocateEx はInterlockedIncrement ルーチンを呼び出して、この変数をアトミックにインクリメントします。同様に、 MyLookasideListFreeEx ルーチン (図示せず) は InterlockedDecrement ルーチンを呼び出して、この変数をアトミックにデクリメントできます。

ただし、前のコード例の MyContext-NumberOfAllocations> 変数の唯一の目的が、ルックアサイドリストの割り当てに関する統計を収集することだけの場合、アトミックインクリメントとデクリメントはほとんど必要になりません。この場合、増分またはデクリメントが見逃されるリモートの可能性は問題になりません。

ルックアサイドリストのスレッドセーフの詳細については、「Lookaside Listsの使用」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows Vista 以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (「解説」セクションを参照)