ExInterlockedPushEntryList

PSINGLE_LIST_ENTRY
ExInterlockedPushEntryList(
IN PSINGLE_LIST_ENTRY ListHead,
IN PSINGLE_LIST_ENTRY ListEntry,
IN PKSPIN_LOCK Lock
);

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

Parameters

ListHead: Points to the head of the singly linked list into which the specified entry is to be inserted.
ListEntry: Points to the entry to be inserted.
Lock: Points to a caller-supplied spin lock.

Return Value

ExInterlockedPushEntryList returns NULL if the list has no entries. Otherwise, a pointer to the entry that is pushed (the previous list head) is returned.

Comments

The ExInterlocked..EntryList routines manipulate a simple, singly linked list and use a spin lock for MP-safe synchronization. For greater efficiency, consider using the ExInterlocked..EntrySList routines that manipulate a sequenced, singly linked list (an S-List) and use an intrinsic 8-byte compare exchange operation for synchronization, where available.

ExInterlockedPushEntrySList inserts an entry at the head of the specified singly linked list.

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 provide resident storage for the interlocked queue. The ListHead pointers must be set up before the initial call to ExInterlockedPushEntryList.

Drivers that retry I/O operations should use a doubly linked interlocked queue and the ExInterlockedInsert/Remove..List routines.

Any of the Ex..Interlocked routines can be called at DIRQL from a device driver’s ISR or SynchCritSection routine(s), provided that other driver routines do not make calls to the ExInterlockedXxx while running at < DIRQL with the same spin lock. Otherwise, callers of ExInterlockedPushEntryList must be running at IRQL <= DISPATCH_LEVEL.