Fungsi HeapReAlloc (heapapi.h)

  • Artikel

Mengalokasikan blok memori dari timbunan. Fungsi ini memungkinkan Anda mengubah ukuran blok memori dan mengubah properti blok memori lainnya. Memori yang dialokasikan tidak dapat dipindahkan.

Sintaks

DECLSPEC_ALLOCATOR LPVOID HeapReAlloc(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem,
  [in] SIZE_T                 dwBytes
);

Parameter

[in] hHeap

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

[in] dwFlags

Opsi realokasi tumpukan. Menentukan nilai akan menggantikan nilai terkait yang ditentukan dalam parameter flOptions saat heap dibuat dengan menggunakan fungsi HeapCreate . Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai Makna
HEAP_GENERATE_EXCEPTIONS
0x00000004
 Sistem operasi memunculkan 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 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 timbunan proses. Sistem dapat membuat utas tambahan dalam proses aplikasi, seperti handler CTRL+C, yang secara bersamaan mengakses timbunan proses.
HEAP_REALLOC_IN_PLACE_ONLY
0x00000010
 Tidak mungkin ada gerakan saat merealokasi blok memori. Jika nilai ini tidak ditentukan, fungsi dapat memindahkan blok ke lokasi baru. Jika nilai ini ditentukan dan blok tidak dapat diubah ukurannya tanpa pemindahan, fungsi gagal, sehingga blok memori asli tidak berubah.
HEAP_ZERO_MEMORY
0x00000008
 Jika permintaan realokasi adalah untuk ukuran yang lebih besar, wilayah memori tambahan di luar ukuran asli diinisialisasi ke nol. Isi blok memori hingga ukuran aslinya tidak terpengaruh.

[in] lpMem

Penunjuk ke blok memori yang di-realokasi fungsi. Penunjuk ini dikembalikan oleh panggilan sebelumnya ke fungsi HeapAlloc atau HeapReAlloc .

[in] dwBytes

Ukuran baru blok memori, dalam byte. Ukuran blok memori dapat ditingkatkan atau dikurangi dengan menggunakan fungsi ini.

Jika heap yang ditentukan oleh parameter hHeap adalah heap "non-growable", 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 kembali.

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. Untuk informasi selengkapnya, lihat GetExceptionCode.

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

Perataan memori yang dikembalikan oleh HeapReAllocMEMORY_ALLOCATION_ALIGNMENT di WinNT.h:

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

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

Keterangan

Jika HeapReAlloc berhasil, heapReAlloc mengalokasikan setidaknya jumlah memori yang diminta.

Jika HeapReAlloc gagal, memori asli tidak dikosongkan, dan handel dan penunjuk asli masih valid.

HeapReAlloc dijamin akan mempertahankan konten memori yang direalokasikan, bahkan jika memori baru dialokasikan di lokasi yang berbeda. Proses mempertahankan konten memori melibatkan operasi salinan memori yang berpotensi sangat memakan waktu.

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

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.

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 Timbunan

HeapAlloc

HeapFree

Fungsi Manajemen Memori

Api Vertdll tersedia di enklave VBS