ExInitializeNPagedLookasideList

VOID
ExInitializeNPagedLookasideList(
IN PNPAGED_LOOKASIDE_LIST Lookaside,
IN PALLOCATE_FUNCTION Allocate, /* optional */
IN PFREE_FUNCTION Free, /* optional */
IN ULONG Flags,
IN ULONG Size,
IN ULONG Tag,
IN USHORT Depth
);

ExInitializeNPagedLookasideList initializes a lookaside list of nonpaged memory. After a successful initialization, fixed-size blocks can be allocated from and freed to the lookaside list.

Parameters

Lookaside

Points to the caller-supplied lookaside list header to be initialized. The list header must be allocated from nonpaged memory and is defined as follows:

typedef struct _NPAGED_LOOKASIDE_LIST {
    SLIST_HEADER ListHead;
    USHORT Depth;
    USHORT Pad;
    ULONG TotalAllocates;
    ULONG AllocateMisses;
    ULONG TotalFrees;
    ULONG FreeMisses;
    POOL_TYPE Type;
    ULONG Tag;
    ULONG Size;
    PALLOCATE_FUNCTION Allocate;
    PFREE_FUNCTION Free;
    LIST_ENTRY ListEntry;
    KSPIN_LOCK Lock;
} NPAGED_LOOKASIDE_LIST, *PNPAGED_LOOKASIDE_LIST;

Allocate

Points to an optional, caller-supplied routine for allocating an entry when the lookaside list is empty. If Allocate is NULL, additional entries are allocated using ExAllocatePoolWithTag.

Free

Points to an optional, caller-supplied routine for freeing an entry back to nonpaged pool when the lookaside list has sufficient entries. If no routine is specified, surplus entries are returned to nonpaged pool using ExFreePool.

Flags

Specifies the flags for controlling pool allocation. This parameter can have the value zero or POOL_RAISE_IF_ALLOCATION_FAILURE. In addition to any caller-supplied flags, this routine sets the pool allocation type flag to NonPagedPool.

Size

Specifies the size in bytes of each entry in the lookaside list.

Tag

Specifies the pool tag for lookaside list entries. The Tag is a string of four characters delimited by single quote marks (for example, ‘derF’). The characters are usually specified in reverse order so they are easier to read when dumping pool or tracking pool usage in the debugger.

Depth

Specifies the maximum number of entries that can be on the lookaside list.

Return Value

None.

Comments

ExInitializeNPagedLookasideList does the following:

Zeros the list header counters
Sets the addresses of the allocate and free routines
Initializes the spin lock
Sets the entry size, list depth, list tag, and pool allocation flags

ExInitializeNPagedLookasideList initializes the caller-supplied list header but does not allocate memory for list entries. The initial entries are allocated on an as-needed basis by the Lookaside.Allocate routine. The list becomes populated as entries are freed back to the list. Entries collect on the list until Lookaside.Depth is reached. Once Depth entries are on the list, any additional entries that are freed are returned to nonpaged pool using the Lookaside.Free routine. If the list becomes empty, allocate requests are satisfied by the Lookaside.Allocate routine.

The OS maintains a list of all the nonpaged lookaside lists in use on the system.

For optimal performance, the OS uses an 8-byte compare exchange operation to synchronize access to the lookaside list if such an instruction is available. On platforms where such an instruction is not available, the spin lock is used.

Owners of a nonpaged lookaside list should choose the Depth of the list carefully. The entries on the list consume nonpaged memory, making that memory unavailable to other components on the system. The list Depth should provide a good hit rate on allocations without consuming excessive memory.

If the POOL_ALLOCATE_RAISE_IF_FAILURE flag is set, the system raises an exception instead of returning NULL if an allocate fails.

Callers of ExInitializeNPagedLookasideList must be running at IRQL <= DISPATCH_LEVEL, but are usually running at PASSIVE_LEVEL.