ExInterlockedPushEntryList

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

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

Parameters

ListHead

Pointer to the head of the singly linked list into which the specified entry is to be inserted.

ListEntry

Pointer to the entry to be inserted, which the caller allocated from nonpaged pool.

Lock

Pointer to a caller-supplied spin lock, already initialized with a call to KeInitializeSpinLock.

Return Value

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

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

The ExInterlocked..EntryList routines manipulate a simple, singly linked list and use a spin lock for multiprocessor-safe synchronization. For greater efficiency, use the ExInterlocked..EntrySList routines that manipulate a sequenced, singly linked list (an S-List), rather than a simple singly linked list.

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

ExInterlockedPushEntrySList inserts a caller-allocated entry at the front 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 first call to ExInterlockedPushEntryList. A caller must not be holding this spin lock when it calls ExInterlockedPush/PopEntryList.

The caller also must provide resident storage for the head of the interlocked queue. The memory containing the ListHead should be zero-initialized before the initial call to ExInterlockedPushEntryList.

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.

See Also

ExInitializeSListHead, ExInterlockedInsertTailList, ExInterlockedPushEntrySList, ExInterlockedPopEntryList, KeInitializeSpinLock