Fungsi HeapFree (heapapi.h)

Artikel
02/07/2024

Membebaskan blok memori yang dialokasikan dari heap oleh fungsi HeapAlloc atau HeapReAlloc .

Sintaks

BOOL HeapFree(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem
);

Parameter

[in] hHeap

Handel ke tumpukan yang blok memorinya akan dikosongkan. Handel ini dikembalikan oleh fungsi HeapCreate atau GetProcessHeap .

[in] dwFlags

Opsi heap free. Menentukan nilai berikut menggantikan nilai terkait yang ditentukan dalam parameter flOptions saat heap dibuat dengan menggunakan fungsi HeapCreate .

Nilai	Makna
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 menentukan HEAP_NO_SERIALIZE tambahan 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

Makna

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 menentukan HEAP_NO_SERIALIZE tambahan 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.

[in] lpMem

Pointer ke blok memori yang akan dikosongkan. Penunjuk ini dikembalikan oleh fungsi HeapAlloc atau HeapReAlloc . Penunjuk ini bisa NULL.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Aplikasi dapat memanggil GetLastError untuk informasi kesalahan yang diperluas.

Keterangan

Anda tidak boleh merujuk dengan cara apa pun ke memori yang telah dibebaskan oleh HeapFree. Setelah memori itu dikosongkan, informasi apa pun yang mungkin ada di dalamnya hilang selamanya. Jika Anda memerlukan informasi, jangan kosongkan memori yang berisi informasi. Panggilan fungsi yang mengembalikan informasi tentang memori (seperti HeapSize) mungkin tidak digunakan dengan memori yang dikosongkan, karena dapat mengembalikan data palsu. Memanggil HeapFree dua kali dengan pointer yang sama dapat menyebabkan kerusakan tumpukan, yang mengakibatkan panggilan berikutnya ke HeapAlloc mengembalikan pointer yang sama dua kali.

Serialisasi memastikan pengecualian timbal balik ketika dua utas atau lebih mencoba mengalokasikan atau membebaskan blok secara bersamaan dari timbunan yang sama. Ada biaya performa kecil untuk serialisasi, tetapi harus digunakan setiap kali beberapa utas mengalokasikan dan membebaskan memori dari tumpukan yang sama. Mengatur nilai HEAP_NO_SERIALIZE menghilangkan pengecualian timbal balik 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 heap untuk timbunan tertentu.
Proses ini memiliki beberapa utas, dan aplikasi menyediakan mekanismenya sendiri untuk pengecualian bersama ke timbunan tertentu.

Contoh

Misalnya, lihat Mendapatkan Timbunan Proses.

Persyaratan

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