ExInterlockedPopEntryList

ExInterlockedPopEntryList

PSINGLE_LIST_ENTRY
ExInterlockedPopEntryList(
IN PSINGLE_LIST_ENTRY ListHead,
IN PKSPIN_LOCK Lock
);

ExInterlockedPopEntryList removes an entry from the front 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 from which an entry is to be removed.

Lock

Points to a caller-supplied spin lock.

Return Value

If the list has no entries, a NULL pointer is returned. Otherwise, a pointer to the dequeued entry 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.

ExInterlockedPopEntrySList removes the first entry from 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 the 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 ExInterlockedPopEntryList must be running at IRQL <= DISPATCH_LEVEL.