Export (0) Print
Expand All
Expand Minimize
1 out of 1 rated this helpful - Rate this topic

ExInitializePagedLookasideList routine

The ExInitializePagedLookasideList routine initializes a lookaside list for pageable entries of the specified size.

Syntax


VOID ExInitializePagedLookasideList(
  _Out_     PPAGED_LOOKASIDE_LIST Lookaside,
  _In_opt_  PALLOCATE_FUNCTION Allocate,
  _In_opt_  PFREE_FUNCTION Free,
  _In_      ULONG Flags,
  _In_      SIZE_T Size,
  _In_      ULONG Tag,
  _In_      USHORT Depth
);

Parameters

Lookaside [out]

A pointer to the PAGED_LOOKASIDE_LIST structure to initialize. The caller must use nonpaged system space for the structure, even though the entries in this lookaside list will be allocated from pageable memory. On 64-bit platforms, this structure must be 16-byte aligned.

Allocate [in, optional]

A pointer to either a caller-supplied function for allocating an entry when the lookaside list is empty, or to NULL. If non-NULL, the pointer is to a function with the prototype:


PVOID XxxAllocate(
  __in POOL_TYPE  PoolType,           // PagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

If the Allocate parameter is NULL, subsequent calls to ExAllocateFromPagedLookasideList automatically allocate entries whenever the lookaside list is empty.

Free [in, optional]

A pointer to either a caller-supplied function for freeing an entry whenever the lookaside list is full, or to NULL. If non-NULL, the pointer is to a function with the prototype:


VOID XxxFree(
  __in PVOID  Buffer
);

If the Free parameter is NULL, subsequent calls to ExFreeToPagedLookasideList automatically release the given entry back to paged pool whenever the list is full, that is, currently holding the system-determined maximum number of entries.

Flags [in]

Reserved. Must be zero.

Size [in]

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

Tag [in]

Specifies the pool tag to use when allocating lookaside list entries. For more information about pool tags, see the Tag parameter of ExAllocatePoolWithTag.

Depth [in]

Reserved. Must be zero.

Return value

None

Remarks

After calling ExInitializePagedLookasideList, blocks of the caller-specified Size can be allocated from and freed to the lookaside list with calls to ExAllocateFromPagedLookasideList and ExFreeToPagedLookasideList, respectively. Such dynamically allocated and freed entries can be any data structure or fixed-size buffer that the caller uses while the system is running, particularly if the caller cannot predetermine how many such entries will be in use at any given moment. The layout and contents of each fixed-size entry are caller-determined.

ExInitializePagedLookasideList initializes the system state to track usage of the given lookaside list, as follows:

  • Zero-initializes the counters to be maintained for entries.

  • Stores the entry points of the caller-supplied XxxAllocate and XxxFree routines, if any, or sets these entry points to ExAllocatePoolWithTag and ExFreePool, respectively.

  • Initializes a system spin lock to control allocations from and frees to the lookaside list in a multiprocessor-safe manner if necessary.

  • Stores the caller-supplied entry Size and list Tag.

  • Sets up the system-determined limits (minimum and maximum) on the number of entries to be held in the lookaside list, which can be adjusted subsequently if system-wide demand for entries is higher or lower than anticipated.

  • Sets up the system-determined flags, which control the type of memory from which entries will be allocated subsequently.

The system maintains a set of all lookaside lists in use. As demand for lookaside list entries and on available paged memory varies while the system runs, the system adjusts its limits for the number of entries to be held in each paged lookaside list dynamically.

Drivers must always use explicitly free any lookaside lists they create before unloading. To do otherwise is a serious programming error. Use ExDeletePagedLookasideList to free the list.

ExInitializePagedLookasideList sets up the opaque list head at the caller-supplied location but preallocates no memory for list entries. Subsequently, the initial entries are allocated dynamically as calls to ExAllocateFromPagedLookasideList occur, and these initial entries are held in the lookaside list as reciprocal calls to ExFreeToPagedLookasideList occur. Entries collect in the given lookaside list until the system-determined maximum is reached, whereupon any additional entries are returned to paged pool as they are freed. If the list becomes empty, allocate requests are satisfied by the XxxAllocate function specified at list initialization or by ExAllocatePoolWithTag.

It is more efficient to pass NULL pointers for the Allocate and Free parameters of ExInitializePagedLookasideList whenever the user of a lookaside list does nothing more than allocate and release fixed-size entries. However, any component that uses a lookaside list might supply these functions to do additional caller-determined processing, such as tracking its own dynamic memory usage by maintaining state about the number of entries it allocates and frees.

If the caller of ExInitializePagedLookasideList supplies an XxxAllocate function, that function must allocate entries for the lookaside list using the given input parameters when it calls ExAllocatePoolWithTag.

Starting with Windows Vista, a similar routine, ExInitializeLookasideListEx, initializes a lookaside list that is described by a LOOKASIDE_LIST_EX structure. Unlike the XxxAllocate and XxxFree routines for a lookaside list that uses a PAGED_LOOKASIDE_LIST structure, the allocation and deallocation routines for a lookaside list that uses the LOOKASIDE_LIST_EX structure receive a context pointer as an input parameter. These routines can use this context to store private data for the lookaside list. If your driver is intended to run only in Windows Vista and later versions of Windows, consider using ExInitializeLookasideListEx instead of ExInitializePagedLookasideList. For more information, see Using Lookaside Lists.

Requirements

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

Ntoskrnl.lib

IRQL

<= APC_LEVEL

DDI compliance rules

IrqlExApcLte2, HwStorPortProhibitedDDIs

See also

ExAllocateFromPagedLookasideList
ExAllocatePoolWithTag
ExDeletePagedLookasideList
ExFreePool
ExFreeToPagedLookasideList
ExInitializeLookasideListEx
ExInitializeNPagedLookasideList
LOOKASIDE_LIST_EX
PAGED_LOOKASIDE_LIST

 

 

Send comments about this topic to Microsoft

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.