ExInitializePagedLookasideList

VOID
ExInitializePagedLookasideList(
IN PPAGED_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
);

ExInitializePagedLookasideList initializes a lookaside list of paged 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 _PAGED_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;
    FAST_MUTEX Lock;
} PAGED_LOOKASIDE_LIST, *PPAGED_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 Free is NULL, 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 PagedPool.

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 using the PoolHitTag variable in the debugger.

Depth

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

Return Value

None.

Comments

ExInitializePagedLookasideList does the following:

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

ExInitializePagedLookasideList initializes the 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 paged 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 paged lookaside lists being used 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 fast mutex is used.

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

Callers of ExInitializePagedLookasideList must be running at IRQL < DISPATCH_LEVEL.