Fungsi HeapCompact (heapapi.h)

Artikel
08/15/2024

Mengembalikan ukuran blok bebas berkomitmen terbesar dalam tumpukan yang ditentukan. Jika Disable heap coalesce pada bendera global gratis diatur, fungsi ini juga menyaring blok memori bebas yang berdekatan dalam tumpukan.

Sintaksis

SIZE_T HeapCompact(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags
);

Parameter

[in] hHeap

Pegangan ke timbunan. Handel ini dikembalikan oleh fungsi HeapCreate atau GetProcessHeap.

[in] dwFlags

Opsi akses timbunan. Parameter ini bisa menjadi nilai berikut.

Nilai	Arti
HEAP_NO_SERIALIZE 0x00000001	Akses berseri tidak akan digunakan. Untuk informasi selengkapnya, lihat Keterangan. Untuk memastikan bahwa akses berseri dinonaktifkan untuk semua panggilan ke fungsi ini, tentukan HEAP_NO_SERIALIZE dalam panggilan ke HeapCreate. Dalam hal ini, tidak perlu juga menentukan HEAP_NO_SERIALIZE dalam panggilan fungsi ini. Jangan tentukan nilai ini saat mengakses timbunan proses. Sistem dapat membuat utas tambahan dalam proses aplikasi, seperti handler CTRL+C, yang secara bersamaan mengakses timbunan proses.

Nilai

Arti

HEAP_NO_SERIALIZE
0x00000001

Akses berseri tidak akan digunakan.

Untuk informasi selengkapnya, lihat Keterangan.

Untuk memastikan bahwa akses berseri dinonaktifkan untuk semua panggilan ke fungsi ini, tentukan HEAP_NO_SERIALIZE dalam panggilan ke HeapCreate. Dalam hal ini, tidak perlu juga menentukan HEAP_NO_SERIALIZE dalam panggilan fungsi ini.

Jangan tentukan nilai ini saat mengakses timbunan proses. Sistem dapat membuat utas tambahan dalam proses aplikasi, seperti handler CTRL+C, yang secara bersamaan mengakses timbunan proses.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian adalah ukuran blok bebas berkomitmen terbesar dalam tumpukan, dalam byte.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Dalam kasus yang tidak mungkin bahwa sama sekali tidak ada ruang yang tersedia dalam timbunan, nilai pengembalian fungsi adalah nol, dan GetLastError mengembalikan nilai NO_ERROR.

Komentar

Fungsi HeapCompact terutama berguna untuk penelusuran kesalahan. Biasanya, sistem memampatkan tumpukan setiap kali fungsi HeapFree dipanggil, dan fungsi HeapCompact mengembalikan ukuran blok bebas terbesar dalam tumpukan tetapi tidak memampatkan tumpukan lebih lanjut. Jika Nonaktifkan heap coalesce pada bendera global gratis diatur selama penelusuran kesalahan, sistem tidak memampatkan tumpukan dan memanggil fungsi HeapCompact memadamkan tumpukan. Untuk informasi selengkapnya tentang bendera global, lihat dokumentasi GFlags .

Tidak ada jaminan bahwa aplikasi dapat berhasil mengalokasikan blok memori dari ukuran yang dikembalikan oleh HeapCompact. Utas lain atau ambang penerapan dapat mencegah alokasi tersebut.

Serialisasi memastikan pengecualian bersama ketika dua utas atau lebih mencoba mengalokasikan atau membebaskan blok secara bersamaan dari tumpukan yang sama. Ada biaya performa kecil untuk serialisasi, tetapi harus digunakan setiap kali beberapa utas mengalokasikan dan membebaskan memori dari timbunan yang sama. Mengatur nilai HEAP_NO_SERIALIZE menghilangkan pengecualian timbunan bersama pada tumpukan. Tanpa serialisasi, dua utas atau lebih yang menggunakan handel tumpukan yang sama mungkin mencoba mengalokasikan atau membebaskan memori secara bersamaan, kemungkinan menyebabkan kerusakan dalam tumpukan. Oleh karena itu, nilai HEAP_NO_SERIALIZE dapat digunakan dengan aman hanya dalam situasi berikut:

Proses ini hanya memiliki satu utas.
Proses ini memiliki beberapa utas, tetapi hanya satu utas yang memanggil fungsi timbunan untuk tumpukan tertentu.
Proses ini memiliki beberapa utas, dan aplikasi menyediakan mekanismenya sendiri untuk pengecualian bersama ke tumpukan tertentu.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows XP [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	heapapi.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

Fungsi Timbunan

HeapCreate

HeapValidate

Fungsi Manajemen Memori

Vertdll API tersedia di enklave VBS

Bagikan melalui