Fungsi ExInitializeLookasideListEx (wdm.h)
Rutinitas ExInitializeLookasideListEx menginisialisasi daftar lookaside.
Sintaks
NTSTATUS ExInitializeLookasideListEx(
[out] PLOOKASIDE_LIST_EX Lookaside,
[in, optional] PALLOCATE_FUNCTION_EX Allocate,
[in, optional] PFREE_FUNCTION_EX Free,
[in] POOL_TYPE PoolType,
[in] ULONG Flags,
[in] SIZE_T Size,
[in] ULONG Tag,
[in] USHORT Depth
);
Parameter
[out] Lookaside
Penunjuk ke struktur LOOKASIDE_LIST_EX untuk diinisialisasi. Saat dikembalikan, struktur ini menjelaskan daftar lookaside kosong. Pemanggil harus menggunakan ruang sistem tidak bertumpuk untuk struktur ini, terlepas dari apakah entri dalam daftar lookaside dialokasikan dari memori halaman atau tidak di-halaman. Pada platform 64-bit, struktur ini harus selaras dengan 16 byte.
[in, optional] Allocate
Penunjuk ke rutinitas LookasideListAllocateEx yang disediakan penelepon yang mengalokasikan entri daftar lookaside baru. Rutinitas ExAllocateFromLookasideListEx memanggil rutinitas LookasideListAllocateEx ini jika daftar lookaside kosong (tidak berisi entri). Parameter ini bersifat opsional dan dapat ditentukan sebagai NULL jika rutinitas alokasi kustom tidak diperlukan. Jika parameter ini ADALAH NULL, panggilan ke ExAllocateFromPagedLookasideList secara otomatis mengalokasikan penyimpanan halaman atau tidak berpaginasi (sebagaimana ditentukan oleh parameter PoolType ) untuk entri baru.
[in, optional] Free
Penunjuk ke rutinitas LookasideListFreeEx yang disediakan penelepon yang membebaskan entri daftar lookaside yang dialokasikan sebelumnya. Rutinitas ExFreeToPagedLookasideList memanggil rutinitas LookasideListFreeEx ini jika daftar lookaside penuh (artinya, daftar sudah berisi jumlah entri maksimum, seperti yang ditentukan oleh sistem operasi). Parameter ini bersifat opsional dan dapat ditentukan sebagai NULL jika rutinitas dealokasi kustom tidak diperlukan. Jika parameter ini ADALAH NULL, panggilan ke ExFreeToPagedLookasideList secara otomatis membebaskan penyimpanan untuk entri yang ditentukan.
[in] PoolType
Menentukan tipe kumpulan entri dalam daftar tampilan. Atur parameter ini ke nilai enumerasi POOL_TYPE yang valid.
[in] Flags
Menentukan nilai bendera opsional untuk mengubah perilaku default dari rutinitas LookasideListAllocateEx . Atur parameter ini ke nol atau ke salah satu bit bendera EX_LOOKASIDE_LIST_EX_FLAGS_XXX berikut.
| Bit bendera | Deskripsi |
|---|---|
| EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL | Jika alokasi gagal, ajukan pengecualian. |
| EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE | Jika alokasi gagal, kembalikan NULL alih-alih menaikkan pengecualian. Bendera ini ditujukan untuk digunakan dengan rutinitas alokasi, seperti ExAllocatePoolWithQuotaTag, yang membebankan kuota untuk penggunaan kumpulan. |
Kedua bit bendera ini saling eksklusif.
Jika Alokasikanadalah NULL, atur Bendera ke nol atau EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, tetapi tidak untuk EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE. Jika tidak, perilaku rutinitas alokasi default tidak ditentukan.
Jika Bendera = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, nilai parameter PoolType adalah bitwise ORed dengan bit bendera POOL_RAISE_IF_ALLOCATION_FAILURE untuk membentuk nilai parameter PoolType yang diteruskan ke rutinitas LookasideListAllocateEx . Rutinitas LookasideListAllocateEx dapat meneruskan nilai PoolType ini, tanpa modifikasi, ke rutinitas ExAllocatePoolWithTag . Untuk informasi selengkapnya tentang bendera POOL_RAISE_IF_ALLOCATION_FAILURE, lihat ExAllocatePoolWithTag.
Jika Bendera = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, nilai parameter PoolType adalah bitwise ORed dengan bit bendera POOL_QUOTA_FAIL_INSTEAD_OF_RAISE untuk membentuk nilai parameter PoolType yang diteruskan ke rutinitas LookasideListAllocateEx . Rutinitas LookasideListAllocateEx dapat meneruskan nilai PoolType ini, tanpa modifikasi, ke rutinitas ExAllocatePoolWithQuotaTag . Untuk informasi selengkapnya tentang bendera POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, lihat ExAllocatePoolWithQuotaTag.
[in] Size
Menentukan ukuran, dalam byte, dari setiap entri dalam daftar tampilan.
[in] Tag
Menentukan tag kumpulan empat byte yang akan digunakan untuk menandai penyimpanan yang dialokasikan untuk entri daftar lookaside. Untuk informasi selengkapnya tentang tag kumpulan, lihat deskripsi parameter Tag di ExAllocatePoolWithTag.
[in] Depth
Dicadangkan. Selalu atur parameter ini ke nol.
Nilai kembali
ExInitializeLookasideListEx mengembalikan STATUS_SUCCESS jika panggilan berhasil. Nilai yang mungkin dikembalikan termasuk kode kesalahan berikut:
| Menampilkan kode | Deskripsi |
|---|---|
| STATUS_INVALID_PARAMETER_4 | Nilai parameter PoolType tidak valid. |
| STATUS_INVALID_PARAMETER_5 | Nilai parameter Bendera tidak valid. |
Keterangan
Driver harus memanggil rutinitas ini untuk menginisialisasi daftar lookaside sebelum driver dapat mulai menggunakan daftar. Daftar lookaside adalah kumpulan buffer ukuran tetap yang dapat dikelola driver secara lokal untuk mengurangi jumlah panggilan ke rutinitas alokasi sistem dan, dengan demikian, untuk meningkatkan performa. Buffer disimpan sebagai entri dalam daftar lookaside. Semua entri dalam daftar memiliki ukuran yang sama dan seragam, yang ditentukan oleh parameter Ukuran .
Setelah ExInitializeLookasideListEx kembali, daftar lookaside diinisialisasi tetapi tidak berisi entri. Ketika klien memanggil rutinitas ExAllocateFromLookasideListEx untuk meminta entri, rutinitas ini menentukan bahwa daftar lookaside kosong dan memanggil rutinitas LookasideListAllocateEx yang disediakan driver untuk mengalokasikan penyimpanan secara dinamis untuk entri baru. Entri tambahan mungkin dialokasikan sebagai respons terhadap permintaan serupa dari klien. Kemudian, ketika klien memanggil ExFreeToLookasideListEx untuk merilis entri ini, rutinitas ini menyisipkan entri ke dalam daftar lookaside. Jika jumlah entri dalam daftar mencapai batas yang ditentukan oleh sistem operasi, ExFreeToLookasideListEx berhenti menambahkan entri lebih lanjut ke daftar dan sebaliknya meneruskan entri ini ke rutinitas LookasideListFreeEx yang disediakan driver untuk dibebaskan.
Jika driver tidak menyediakan rutinitas LookasideListAllocateEx dan LookasideListFreeEx , rutinitas ExAllocateFromLookasideListEx dan ExFreeToLookasideListEx menggunakan rutinitas alokasi dan dealokasi default sebagai gantinya.
Tidak ada manfaat untuk menyediakan rutinitas LookasideListAllocateEx dan LookasideListFreeEx yang tidak melakukan apa pun selain memanggil ExAllocatePoolWithTag dan ExFreePool. Efek yang sama dapat dicapai dengan performa yang lebih baik hanya dengan mengatur parameter Alokasikan dan Gratis ke NULL.
Sebelum driver dibongkar, driver harus secara eksplisit membebaskan daftar tampilan apa pun yang dibuatnya. Kegagalan untuk melakukannya adalah kesalahan pemrograman yang serius. Panggil rutinitas ExDeleteLookasideListEx untuk membebaskan daftar tampilan. Rutinitas ini membebaskan penyimpanan untuk entri yang tersisa dalam daftar lookaside yang ditentukan lalu menghapus daftar dari set daftar lookaside aktif di seluruh sistem.
Sistem operasi melacak semua daftar lookaside yang saat ini sedang digunakan. Karena jumlah memori tidak bertumpuk yang tersedia dan permintaan untuk entri daftar pencarian bervariasi dari waktu ke waktu, sistem operasi secara dinamis menyesuaikan batasnya untuk jumlah maksimum entri di setiap daftar lookaside yang tidak dipagasi.
Di Windows 2000 dan versi Windows yang lebih baru, daftar lookaside yang berisi entri halaman atau tidak bertumpuk dapat dijelaskan oleh struktur PAGED_LOOKASIDE_LIST atau NPAGED_LOOKASIDE_LIST .
Untuk informasi selengkapnya tentang daftar lookaside, lihat Menggunakan lookaside Lists.
Pemanggil ExInitializeLookasideListEx dapat berjalan di IRQL <= DISPATCH_LEVEL, tetapi biasanya berjalan di IRQL = PASSIVE_LEVEL.
Contoh
Rutinitas LookasideListAllocateEx dan LookasideListFreeEx yang disediakan driver keduanya menerima parameter Lookaside yang menunjuk ke struktur LOOKASIDE_LIST_EX yang menjelaskan daftar lookaside. Rutinitas dapat menggunakan parameter ini untuk mengakses data privat yang telah dikaitkan driver dengan daftar lookaside. Misalnya, driver mungkin mengalokasikan instans struktur berikut untuk mengumpulkan data privat untuk setiap daftar lookaside yang dibuatnya:
typedef struct
{
ULONG NumberOfAllocations; // number of entries allocated
ULONG NumberOfFrees; // number of entries freed
LOOKASIDE_LIST_EX LookasideField;
} MY_PRIVATE_DATA;
Driver dapat menginisialisasi daftar lookaside seperti yang ditunjukkan dalam contoh kode berikut:
#define ENTRY_SIZE 256
#define MY_POOL_TAG 'tsLL'
MY_PRIVATE_DATA *MyContext;
NTSTATUS status = STATUS_SUCCESS;
MyContext = ExAllocatePoolWithTag(NonPagedPool, sizeof(MY_PRIVATE_DATA), MY_POOL_TAG);
if (MyContext)
{
MyContext.NumberOfAllocations = 0;
MyContext.NumberOfFrees = 0;
status = ExInitializeLookasideListEx(
&MyContext.LookasideField,
MyLookasideListAllocateEx,
MyLookasideListFreeEx,
NonPagedPool,
0,
ENTRY_SIZE,
MY_POOL_TAG,
0);
}
else
{
status = STATUS_INSUFFICIENT_RESOURCES;
}
Contoh kode berikut menunjukkan bagaimana rutinitas LookasideListAllocateEx dapat menggunakan parameter Lookaside-nya untuk mengakses data privat yang terkait dengan daftar lookaside:
PVOID
MyLookasideListAllocateEx(
__in POOL_TYPE PoolType,
__in SIZE_T NumberOfBytes,
__in ULONG Tag,
__inout PLOOKASIDE_LIST_EX Lookaside)
{
MY_PRIVATE_DATA *MyContext;
PVOID NewEntry;
MyContext = CONTAINING_RECORD(Lookaside, MY_PRIVATE_DATA, LookasideField);
NewEntry = ExAllocatePoolWithTag(PoolType, NumberOfBytes, Tag);
if (NewEntry)
{
ULONG NumberOfAllocations = (ULONG) InterlockedIncrement((LONG volatile*)&MyContext->NumberOfAllocations);
}
return NewEntry;
}
Makro CONTAINING_RECORD ditentukan dalam file header Ntdef.h. Rutinitas LookAsideListFreeEx juga dapat menggunakan parameter Lookaside untuk mengakses data privat.
Setelah rutinitas MyLookasideListAllocateEx dalam contoh ini mengembalikan, ExAllocateFromLookasideListEx menyisipkan buffer yang ditunjukkan oleh variabel NewEntry ke dalam daftar lookaside. Untuk membuat operasi penyisipan ini aman, ExAllocateFromLookasideListEx menyinkronkan aksesnya dari daftar lookaside dengan penyisipan daftar lain dan operasi penghapusan yang mungkin dilakukan oleh utas lain. Demikian pula, ketika ExFreeFromLookasideListEx menghapus buffer dari daftar lookaside, ExFreeFromLookasideListEx menyinkronkan aksesnya ke daftar.
ExAllocateFromLookasideListEx dan ExFreeFromLookasideListEx tidak menyinkronkan panggilan mereka ke rutinitas LookasideListAllocateEx dan LookasideListFreeEx yang disediakan driver. Dengan demikian, jika rutinitas MyLookasideListAllocateEx dan MyLookasideListFreeEx dalam contoh kode sebelumnya harus aman untuk utas, driver harus memberikan sinkronisasi yang diperlukan.
Contoh rutinitas, MyLookasideListAllocateEx, menyinkronkan aksesnya dari variabel MyContext-NumberOfAllocations> dengan utas lain yang mungkin mengalami kenaikan dan penurunan variabel ini. Untuk menyediakan sinkronisasi ini, MyLookasideListAllocateEx memanggil rutinitas InterlockedIncrement untuk meningkatkan variabel ini secara atomik. Demikian pula, rutinitas MyLookasideListFreeEx (tidak ditampilkan) dapat memanggil rutinitas InterlockedDecrement untuk mengurangi variabel ini secara atomik.
Namun, jika satu-satunya tujuan dari variabel MyContext-NumberOfAllocations> dalam contoh kode sebelumnya hanyalah untuk mengumpulkan statistik pada alokasi daftar lookaside, kenaikan dan penurunan atom hampir tidak diperlukan. Dalam hal ini, kemungkinan jarak jauh dari kenaikan atau penurunan yang terlewat seharusnya tidak menjadi perhatian.
Untuk informasi selengkapnya tentang keamanan utas untuk daftar tampilan, lihat Menggunakan Lists Lookaside.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Tersedia dimulai dengan Windows Vista. |
| Target Platform | Universal |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL (lihat bagian Keterangan) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk