HeapAlloc 関数 (heapapi.h)

ヒープからメモリ ブロックを割り当てます。 割り当てられたメモリは移動できません。

構文

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

パラメーター

[in] hHeap

メモリの割り当て元となるヒープへのハンドル。 このハンドルは、 HeapCreate 関数または GetProcessHeap 関数によって返されます。

[in] dwFlags

ヒープ割り当てオプション。 これらの値のいずれかを指定すると、 HeapCreate でヒープが作成されたときに指定された対応する値がオーバーライドされます。 このパラメーターには、次の 1 つ以上の値を指定できます。

[in] dwBytes

割り当てるバイト数。

hHeap パラメーターで指定されたヒープが "非拡張" ヒープである場合、dwBytes は0x7FFF8未満である必要があります。 0 以外の値を指定して HeapCreate 関数を呼び出して、拡張不可能なヒープを作成します。

戻り値

関数が成功した場合、戻り値は割り当てられたメモリ ブロックへのポインターです。

関数が失敗し、 HEAP_GENERATE_EXCEPTIONSを指定していない場合、戻り値は NULL になります。

関数が失敗し、 HEAP_GENERATE_EXCEPTIONSを指定した場合、次の表に示す例外のいずれかが関数によって生成される場合があります。 特定の例外は、ヒープ破損の性質によって異なります。 詳細については、「 GetExceptionCode」を参照してください。

関数が失敗した場合、 SetLastError は呼び出されません。 アプリケーションは、拡張エラー情報 に対して GetLastError を呼び出すことができません。

注釈

HeapAlloc 関数が成功すると、少なくとも要求されたメモリ量が割り当てられます。

プロセスの既定のヒープからメモリを割り当てるには、GetProcessHeap 関数によって返されるハンドルで HeapAlloc を使用します。

HeapAlloc によって割り当てられたメモリ ブロックを解放するには、HeapFree 関数を使用します。

HeapAlloc によって割り当てられたメモリは移動できません。 HeapAlloc によって返されるアドレスは、メモリ ブロックが解放されるか再割り当てされるまで有効です。メモリ ブロックをロックする必要はありません。 システムはプライベート ヒープを圧縮できないため、断片化される可能性があります。

HeapAlloc によって返されるメモリの配置は、WinNT.h でMEMORY_ALLOCATION_ALIGNMENTされます。

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

さまざまな割り当てサイズで大量のメモリを割り当てるアプリケーションでは、 断片化の少ないヒープ を使用してヒープの断片化を減らすことができます。

シリアル化により、2 つ以上のスレッドが同じヒープからブロックを同時に割り当てたり解放したりしようとすると、相互の除外が保証されます。 シリアル化にはパフォーマンス コストは小さくなりますが、複数のスレッドが同じヒープからメモリを割り当てて解放するたびに使用する必要があります。 HEAP_NO_SERIALIZE値を設定すると、ヒープの相互除外がなくなります。 シリアル化を行わないと、同じヒープ ハンドルを使用する 2 つ以上のスレッドが同時にメモリの割り当てまたは解放を試みる可能性があり、ヒープが破損する可能性があります。 したがって、HEAP_NO_SERIALIZE値は、次の状況でのみ安全に使用できます。

• プロセスに含まれるスレッドは 1 つだけです。
• プロセスには複数のスレッドがありますが、特定のヒープのヒープ関数を呼び出すスレッドは 1 つだけです。
• プロセスには複数のスレッドがあり、アプリケーションは特定のヒープに対する相互除外のための独自のメカニズムを提供します。

例

例については、「 AWE の例」を参照してください。

要件

関連項目

ヒープ関数

HeapFree

HeapReAlloc

メモリ管理関数

VBS エンクレーブで使用できる Vertdll API