ExInterlockedInsertHeadList

PLIST_ENTRY
ExInterlockedInsertHeadList(
IN PLIST_ENTRY ListHead,
IN PLIST_ENTRY ListEntry,
IN PKSPIN_LOCK Lock
);

ExInterlockedInsertHeadList inserts an entry at the head of a doubly linked list so that access to the list is synchronized in a multiprocessor-safe way.

Parameters

ListHead: Points to the head of the doubly linked list into which an entry is to be inserted.
ListEntry: Points to the entry to be inserted at the head of the list.
Lock: Points to a caller-supplied spin lock used to synchronize access to the list.

Return Value

ExInterlockedInsertHeadList returns a pointer to the entry that was at the head of the interlocked queue before this entry was inserted. If the queue was empty, it returns NULL.

Comments

Support routines that do interlocked operations are assumed to be incapable of causing a page fault. That is, neither their code nor any of the data they touch can cause a page fault without bringing down the system. They use spin locks to achieve atomicity in SMP machines. The caller must provide resident storage for the Lock, which must be initialized with KeInitializeSpinLock before the initial call to an ExInterlockedXxx.

The caller also must supply resident storage for the interlocked queue. The ListHead must be initialized with InitializedListHead before the initial call to an ExInterlocked..List.

If the caller uses only ExInterlocked..List routines to manipulate the list, then these routines can be called from a single IRQL that is <= DIRQL. If other driver routines access the list using any other routines, such as the noninterlocked InsertHeadList, then callers of ExInterlocked..List must be at <= DISPATCH_LEVEL.

Usually, drivers call ExInterlockedInsertTailList to insert an IRP into a driver-managed interlocked queue. They call ExInterlockedInsertHeadList only to requeue an IRP for a retry.