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 つ以上の値を指定できます。
| 値 | 意味 |
|---|---|
|
システムは、 NULL を返す代わりに、メモリ不足状態などの関数エラーを示す例外を発生させます。
この関数のすべての呼び出しに対して例外が生成されるようにするには、HeapCreate の呼び出しで HEAP_GENERATE_EXCEPTIONSを指定します。 この場合、この関数呼び出しで HEAP_GENERATE_EXCEPTIONS をさらに指定する必要はありません。 |
|
シリアル化されたアクセスは、この割り当てには使用されません。
詳細については、「解説」を参照してください。 この関数のすべての呼び出しでシリアル化されたアクセスが無効になっていることを確認するには、HeapCreate の呼び出しで HEAP_NO_SERIALIZE を指定します。 この場合、この関数呼び出しで HEAP_NO_SERIALIZE をさらに指定する必要はありません。 この値は、プロセスの既定のヒープにアクセスするときに指定しないでください。 システムは、アプリケーションのプロセス内に、プロセスの既定のヒープに同時にアクセスする追加のスレッド (Ctrl + C ハンドラーなど) を作成する場合があります。 |
|
割り当てられたメモリは 0 に初期化されます。 それ以外の場合、メモリは 0 に初期化されません。 |
[in] dwBytes
割り当てるバイト数。
hHeap パラメーターで指定されたヒープが "非拡張" ヒープである場合、dwBytes は0x7FFF8未満である必要があります。 0 以外の値を指定して HeapCreate 関数を呼び出して、拡張不可能なヒープを作成します。
戻り値
関数が成功した場合、戻り値は割り当てられたメモリ ブロックへのポインターです。
関数が失敗し、 HEAP_GENERATE_EXCEPTIONSを指定していない場合、戻り値は NULL になります。
関数が失敗し、 HEAP_GENERATE_EXCEPTIONSを指定した場合、次の表に示す例外のいずれかが関数によって生成される場合があります。 特定の例外は、ヒープ破損の性質によって異なります。 詳細については、「 GetExceptionCode」を参照してください。
| 例外コード | 説明 |
|---|---|
| STATUS_NO_MEMORY | 使用可能なメモリまたはヒープの破損がないため、割り当ての試行が失敗しました。 |
| STATUS_ACCESS_VIOLATION | ヒープ破損または関数パラメーターが不適切なため、割り当ての試行が失敗しました。 |
関数が失敗した場合、 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 の例」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | heapapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |