Функция KeInsertHeadQueue (ntifs.h)

Статья
08/07/2023

Подпрограмма 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;

Член	Значение
Верхняя часть	Заголовок очереди
EntryListHead	Указатель на первую запись в очереди
CurrentCount	Количество записей в очереди
MaximumCount	Максимальное количество записей, которые может содержать очередь
ThreadListHead	Указатель на первую запись в списке потоков

[in, out] Entry

Указатель на вставленную запись очереди. Этот указатель должен быть адресом постоянного системного пространства.

Возвращаемое значение

KeInsertHeadQueue возвращает предыдущее состояние сигнала заданной очереди. Если до вызова KeInsertHeadQueue было задано значение 0 (без сигнала), keInsertHeadQueue возвращает ноль, то есть записи не помещались в очередь. Если это ненулевая (сигнальная), KeInsertHeadQueue возвращает количество записей, которые были поставлены в очередь до вызова KeInsertHeadQueue .

Записи, которые будут помещены в очередь с помощью KeInsertHeadQueue , должны быть выделены из непагрегированного пула. Например, память для записей, определяемых вызывающим объектом, можно выделить с помощью ExAllocatePoolWithTag. Если вызывающий объект выделяет записи фиксированного размера, создание списка lookaside с помощью ExInitializeNPagedLookasideList и выделение из него с помощью ExAllocateFromNPagedLookasideList более эффективно, чем частые вызовы ExAllocatePoolWithTag, особенно для записей, размер которых не кратен PAGE_SIZE.

Если какие-либо потоки ожидают объекта очереди при вызове KeInsertHeadQueue , этот вызов удовлетворяет ожиданию одного потока. Поток отправляется для выполнения с помощью заданного указателя входа .

Если при вызове KeInsertHeadQueue потоки не ожидают объекта очереди, в очередь вставляется данная запись, а состояние сигнала объекта очереди увеличивается.

Дополнительные сведения об использовании внутренних очередей, управляемых драйвером, см. в разделе Очереди, управляемые драйвером.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIs(storport)