KeInsertHeadQueue 関数 (ntifs.h)

[アーティクル]
03/05/2024

KeInsertHeadQueue ルーチンは、エントリをすぐに使用してスレッド待機を満たすことができない場合に、指定されたキューの先頭にエントリを挿入します。

構文

LONG KeInsertHeadQueue(
  [in, out] PRKQUEUE    Queue,
  [in, out] PLIST_ENTRY Entry
);

パラメーター

[in, out] Queue

呼び出し元が非ページプールに常駐ストレージを提供する初期化されたキューオブジェクトへのポインター。この構造体は次のように定義されます。

typedef struct _KQUEUE {
    DISPATCHER_HEADER Header;
    LIST_ENTRY EntryListHead;
    ULONG CurrentCount;
    ULONG MaximumCount;
    LIST_ENTRY ThreadListHead;
} KQUEUE, *PKQUEUE, *RESTRICTED_POINTER PRKQUEUE;

メンバー	意味
Header	キューヘッダー
EntryListHead	キュー内の最初のエントリへのポインター
CurrentCount	キュー内のエントリの数
MaximumCount	キューに含めることができるエントリの最大数
ThreadListHead	スレッドリスト内の最初のエントリへのポインター

[in, out] Entry

挿入するキューエントリへのポインター。このポインターは、常駐システム・スペース・アドレスでなければなりません。

戻り値

KeInsertHeadQueue は、指定されたキューの以前のシグナル状態を返します。 KeInsertHeadQueue が呼び出される前に 0 (シグナル化されていない) に設定された場合、KeInsertHeadQueue は 0 を返します。つまり、エントリがキューに入れられなかったことを意味します。 0 以外 (シグナル) の場合、 KeInsertHeadQueue は 、KeInsertHeadQueue が呼び出される前にキューに登録されたエントリの数を返します。

注釈

KeInsertHeadQueue によってキューに登録されるエントリは、非ページプールから割り当てる必要があります。たとえば、呼び出し元定義エントリのメモリは、ExAllocatePoolWithTag を使用して割り当てることができます。呼び出し元が固定サイズのエントリを割り当てる場合、 ExInitializeNPagedLookasideList を使用してルックアサイドリストを作成し、 ExAllocateFromNPagedLookasideList を使用して割り当てる方が、 ExAllocatePoolWithTag を頻繁に呼び出すよりも効率的です。特に、サイズがPAGE_SIZEの倍数ではないエントリの場合です。

KeInsertHeadQueue が呼び出されたときにキューオブジェクトで待機しているスレッドがある場合、この呼び出しによって 1 つのスレッドの待機が満たされます。スレッドは、指定された Entry ポインターを使用して実行するためにディスパッチされます。

KeInsertHeadQueue が呼び出されたときにキューオブジェクトで現在待機しているスレッドがない場合は、指定されたエントリがキューに挿入され、キューオブジェクトのシグナル状態がインクリメントされます。

ドライバーで管理される内部キューの使用の詳細については、「 Driver-Managed Queues」を参照してください。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	ntifs.h (Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport)