Fungsi HeapAlloc (heapapi.h)

Mengalokasikan blok memori dari heap. Memori yang dialokasikan tidak dapat dipindahkan.

Sintaks

DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags,
  [in] SIZE_T dwBytes
);

Parameter

[in] hHeap

Handel ke timbunan dari mana memori akan dialokasikan. Handel ini dikembalikan oleh fungsi HeapCreate atau GetProcessHeap .

[in] dwFlags

Opsi alokasi timbunan. Menentukan salah satu nilai ini akan menggantikan nilai terkait yang ditentukan ketika tumpukan dibuat dengan HeapCreate. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
HEAP_GENERATE_EXCEPTIONS 0x00000004	Sistem akan menaikkan pengecualian untuk menunjukkan kegagalan fungsi, seperti kondisi di luar memori, alih-alih mengembalikan NULL. Untuk memastikan bahwa pengecualian dihasilkan untuk semua panggilan ke fungsi ini, tentukan HEAP_GENERATE_EXCEPTIONS dalam panggilan ke HeapCreate. Dalam hal ini, tidak perlu menentukan HEAP_GENERATE_EXCEPTIONS tambahan dalam panggilan fungsi ini.
HEAP_NO_SERIALIZE 0x00000001	Akses berseri tidak akan digunakan untuk alokasi ini. 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. Nilai ini tidak boleh ditentukan saat mengakses tumpukan default proses. Sistem dapat membuat utas tambahan dalam proses aplikasi, seperti handler CTRL+C, yang secara bersamaan mengakses tumpukan default proses.
HEAP_ZERO_MEMORY 0x00000008	Memori yang dialokasikan akan diinisialisasi ke nol. Jika tidak, memori tidak diinisialisasi ke nol.

[in] dwBytes

Jumlah byte yang akan dialokasikan.

Jika tumpukan yang ditentukan oleh parameter hHeap adalah tumpukan "tidak dapat ditumbuhkan", dwBytes harus kurang dari 0x7FFF8. Anda membuat tumpukan yang tidak dapat tumbuh dengan memanggil fungsi HeapCreate dengan nilai bukan nol.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah penunjuk ke blok memori yang dialokasikan.

Jika fungsi gagal dan Anda belum menentukan HEAP_GENERATE_EXCEPTIONS, nilai yang dikembalikan adalah NULL.

Jika fungsi gagal dan Anda telah menentukan HEAP_GENERATE_EXCEPTIONS, fungsi dapat menghasilkan salah satu pengecualian yang tercantum dalam tabel berikut. Pengecualian khusus tergantung pada sifat kerusakan tumpukan. Untuk informasi selengkapnya, lihat GetExceptionCode.

Kode pengecualian	Deskripsi
STATUS_NO_MEMORY	Upaya alokasi gagal karena kurangnya memori yang tersedia atau kerusakan tumpukan.
STATUS_ACCESS_VIOLATION	Upaya alokasi gagal karena kerusakan tumpukan atau parameter fungsi yang tidak tepat.

Jika fungsi gagal, fungsi tidak memanggil SetLastError. Aplikasi tidak dapat memanggil GetLastError untuk informasi kesalahan yang diperluas.

Keterangan

Jika fungsi HeapAlloc berhasil, fungsi ini mengalokasikan setidaknya jumlah memori yang diminta.

Untuk mengalokasikan memori dari tumpukan default proses, gunakan HeapAlloc dengan handel yang dikembalikan oleh fungsi GetProcessHeap .

Untuk membebaskan blok memori yang dialokasikan oleh HeapAlloc, gunakan fungsi HeapFree .

Memori yang dialokasikan oleh HeapAlloc tidak dapat dipindahkan. Alamat yang dikembalikan oleh HeapAlloc valid sampai blok memori dibebaskan atau direalokasikan; blok memori tidak perlu dikunci. Karena sistem tidak dapat memampatkan tumpukan privat, sistem dapat menjadi terfragmentasi.

Perataan memori yang dikembalikan oleh HeapAllocMEMORY_ALLOCATION_ALIGNMENT di WinNT.h:

#if defined(_WIN64) || defined(_M_ALPHA)
#define MEMORY_ALLOCATION_ALIGNMENT 16
#else
#define MEMORY_ALLOCATION_ALIGNMENT 8
#endif

Aplikasi yang mengalokasikan memori dalam jumlah besar dalam berbagai ukuran alokasi dapat menggunakan tumpukan fragmentasi rendah untuk mengurangi fragmentasi timbunan.

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 tumpukan yang sama. Mengatur nilai HEAP_NO_SERIALIZE menghilangkan pengecualian 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 tumpukan untuk tumpukan tertentu.
• Proses ini memiliki beberapa utas, dan aplikasi menyediakan mekanismenya sendiri untuk pengecualian bersama ke tumpukan tertentu.

Contoh

Misalnya, lihat Contoh AWE.

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

Lihat juga

Fungsi Heap

HeapFree

HeapReAlloc

Fungsi Manajemen Memori

API Vertdll tersedia di enklave VBS