ExInterlockedPopEntryList

The ExInterlockedPopEntryList routine removes an entry from the front of a simple singly linked list so that access to the queue is synchronized in a multiprocessor-safe way.

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

Parameters

ListHead

Pointer to the head of the singly linked list from which an entry is to be removed.

Lock

Pointer to a caller-supplied spin lock.

Return Value

If the list has no entries, ExInterlockedPopEntryList returns a NULL pointer. Otherwise, it returns a pointer to the dequeued entry.

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), instead of 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 queue or an S-List.

ExInterlockedPopEntryList 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. A caller must not be holding this spin lock when it calls ExInterlockedPush/PopEntryList.

The caller also must provide the storage for the interlocked queue. The memory at 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 ExInterlockedPopEntryList must be running at IRQL <= DISPATCH_LEVEL.

See Also

ExInitializeSListHead, ExInterlockedPopEntrySList, ExInterlockedPushEntryList, KeInitializeSpinLock