Fungsi HeapCreate (heapapi.h)

Artikel
02/02/2024

Membuat objek tumpukan privat yang dapat digunakan oleh proses panggilan. Fungsi ini mencadangkan ruang di ruang alamat virtual proses dan mengalokasikan penyimpanan fisik untuk bagian awal yang ditentukan dari blok ini.

Sintaks

HANDLE HeapCreate(
  [in] DWORD  flOptions,
  [in] SIZE_T dwInitialSize,
  [in] SIZE_T dwMaximumSize
);

Parameter

[in] flOptions

Opsi alokasi timbunan. Opsi ini memengaruhi akses berikutnya ke tumpukan baru melalui panggilan ke fungsi heap. Parameter ini bisa 0 atau satu atau beberapa nilai berikut.

Nilai	Makna
HEAP_CREATE_ENABLE_EXECUTE 0x00040000	Semua blok memori yang dialokasikan dari timbunan ini memungkinkan eksekusi kode, jika perangkat keras memberlakukan pencegahan eksekusi data. Gunakan timbunan bendera ini dalam aplikasi yang menjalankan kode dari heap. Jika HEAP_CREATE_ENABLE_EXECUTE tidak ditentukan dan aplikasi mencoba menjalankan kode dari halaman yang dilindungi, aplikasi menerima pengecualian dengan kode status STATUS_ACCESS_VIOLATION.
HEAP_GENERATE_EXCEPTIONS 0x00000004	Sistem memunculkan pengecualian untuk menunjukkan kegagalan (misalnya, kondisi di luar memori) untuk panggilan ke HeapAlloc dan HeapReAlloc alih-alih mengembalikan NULL.
HEAP_NO_SERIALIZE 0x00000001	Akses berseri tidak digunakan ketika fungsi heap mengakses heap ini. Opsi ini berlaku untuk semua panggilan fungsi tumpukan berikutnya. Atau, Anda dapat menentukan opsi ini pada panggilan fungsi timbunan individual. Timbunan fragmentasi rendah (LFH) tidak dapat diaktifkan untuk tumpukan yang dibuat dengan opsi ini. Timbunan yang dibuat dengan opsi ini tidak dapat dikunci. Untuk informasi selengkapnya tentang akses berseri, lihat bagian Keterangan dari topik ini.

Nilai

Makna

HEAP_CREATE_ENABLE_EXECUTE
0x00040000

Semua blok memori yang dialokasikan dari timbunan ini memungkinkan eksekusi kode, jika perangkat keras memberlakukan pencegahan eksekusi data. Gunakan timbunan bendera ini dalam aplikasi yang menjalankan kode dari heap. Jika HEAP_CREATE_ENABLE_EXECUTE tidak ditentukan dan aplikasi mencoba menjalankan kode dari halaman yang dilindungi, aplikasi menerima pengecualian dengan kode status STATUS_ACCESS_VIOLATION.

HEAP_GENERATE_EXCEPTIONS
0x00000004

Sistem memunculkan pengecualian untuk menunjukkan kegagalan (misalnya, kondisi di luar memori) untuk panggilan ke HeapAlloc dan HeapReAlloc alih-alih mengembalikan NULL.

HEAP_NO_SERIALIZE
0x00000001

Akses berseri tidak digunakan ketika fungsi heap mengakses heap ini. Opsi ini berlaku untuk semua panggilan fungsi tumpukan berikutnya. Atau, Anda dapat menentukan opsi ini pada panggilan fungsi timbunan individual.

Timbunan fragmentasi rendah (LFH) tidak dapat diaktifkan untuk tumpukan yang dibuat dengan opsi ini.

Timbunan yang dibuat dengan opsi ini tidak dapat dikunci.

Untuk informasi selengkapnya tentang akses berseri, lihat bagian Keterangan dari topik ini.

[in] dwInitialSize

Ukuran awal timbunan, dalam byte. Nilai ini menentukan jumlah awal memori yang diterapkan untuk tumpukan. Nilai dibulatkan ke atas ke kelipatan ukuran halaman sistem. Nilai harus lebih kecil dari dwMaximumSize.

Jika parameter ini adalah 0, fungsi menerapkan satu halaman. Untuk menentukan ukuran halaman di komputer host, gunakan fungsi GetSystemInfo .

[in] dwMaximumSize

Ukuran maksimum timbunan, dalam byte. Fungsi HeapCreate membulatkandwMaximumSize hingga kelipatan ukuran halaman sistem dan kemudian mencadangkan blok ukuran tersebut di ruang alamat virtual proses untuk tumpukan. Jika permintaan alokasi yang dibuat oleh fungsi HeapAlloc atau HeapReAlloc melebihi ukuran yang ditentukan oleh dwInitialSize, sistem menerapkan halaman memori tambahan untuk tumpukan, hingga ukuran maksimum heap.

Jika dwMaximumSize bukan nol, ukuran heap tetap dan tidak dapat tumbuh melebihi ukuran maksimum. Selain itu, blok memori terbesar yang dapat dialokasikan dari tumpukan sedikit kurang dari 512 KB untuk proses 32-bit dan sedikit kurang dari 1.024 KB untuk proses 64-bit. Permintaan untuk mengalokasikan blok yang lebih besar gagal, bahkan jika ukuran maksimum timbunan cukup besar untuk memuat blok.

Jika dwMaximumSize adalah 0, timbunan dapat tumbuh dalam ukuran. Ukuran timbunan hanya dibatasi oleh memori yang tersedia. Permintaan untuk mengalokasikan blok memori yang lebih besar dari batas untuk tumpukan ukuran tetap tidak gagal secara otomatis; sebaliknya, sistem memanggil fungsi VirtualAlloc untuk mendapatkan memori yang diperlukan untuk blok besar. Aplikasi yang perlu mengalokasikan blok memori besar harus mengatur dwMaximumSize ke 0.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke timbunan yang baru dibuat.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi HeapCreate membuat objek heap privat tempat proses panggilan dapat mengalokasikan blok memori dengan menggunakan fungsi HeapAlloc . Ukuran awal menentukan jumlah halaman yang diterapkan yang dialokasikan pada awalnya untuk tumpukan. Ukuran maksimum menentukan jumlah total halaman yang dipesan. Halaman-halaman ini membuat blok di ruang alamat virtual proses tempat tumpukan dapat tumbuh. Jika permintaan oleh HeapAlloc melebihi ukuran halaman yang diterapkan saat ini, halaman tambahan secara otomatis diterapkan dari ruang yang dipesan ini, jika penyimpanan fisik tersedia.

Windows Server 2003 dan Windows XP: Secara default, timbunan privat yang baru dibuat adalah timbunan standar. Untuk mengaktifkan tumpukan fragmentasi rendah, panggil fungsi HeapSetInformation dengan handel ke tumpukan privat.

Memori objek heap privat hanya dapat diakses oleh proses yang membuatnya. Jika pustaka tautan dinamis (DLL) membuat timbunan privat, tumpukan dibuat di ruang alamat proses yang memanggil DLL, dan hanya dapat diakses oleh proses tersebut.

Sistem menggunakan memori dari tumpukan privat untuk menyimpan struktur dukungan tumpukan, sehingga tidak semua ukuran tumpukan yang ditentukan tersedia untuk proses. Misalnya, jika fungsi HeapAlloc meminta 64 kilobyte (K) dari heap dengan ukuran maksimum 64K, permintaan mungkin gagal karena overhead sistem.

Jika HEAP_NO_SERIALIZE tidak ditentukan (default sederhana), heap akan menserialisasikan akses dalam proses panggilan. Serialisasi memastikan pengecualian bersama ketika dua utas atau lebih mencoba secara bersamaan untuk mengalokasikan atau membebaskan blok 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. Fungsi HeapLock dan HeapUnlock dapat digunakan untuk memblokir dan mengizinkan akses ke tumpukan serial.

Mengatur HEAP_NO_SERIALIZE menghilangkan pengecualian timbunan bersama pada timbunan. Tanpa serialisasi, dua utas atau lebih yang menggunakan handel tumpukan yang sama mungkin mencoba mengalokasikan atau membebaskan memori secara bersamaan, yang dapat menyebabkan kerusakan dalam tumpukan. Oleh karena itu, HEAP_NO_SERIALIZE hanya dapat digunakan dengan aman 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.

Jika fungsi HeapLock dan HeapUnlock dipanggil pada heap yang dibuat dengan bendera HEAP_NO_SERIALIZE , hasilnya tidak terdefinisi.

Untuk mendapatkan handel ke tumpukan default untuk proses, gunakan fungsi GetProcessHeap . Untuk mendapatkan handel ke timbunan default dan timbunan privat yang aktif untuk proses panggilan, gunakan fungsi GetProcessHeaps .

Contoh

Menghitung Tumpukan

Persyaratan


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