HeapCreate 関数 (heapapi.h)
呼び出し元プロセスで使用できるプライベート ヒープ オブジェクトを作成します。 関数は、プロセスの仮想アドレス空間内の領域を予約し、このブロックの指定された初期部分に物理ストレージを割り当てます。
構文
HANDLE HeapCreate(
[in] DWORD flOptions,
[in] SIZE_T dwInitialSize,
[in] SIZE_T dwMaximumSize
);
パラメーター
[in] flOptions
ヒープ割り当てオプション。 これらのオプションは、ヒープ関数の呼び出しを介した新しいヒープへの後続のアクセスに影響します。 このパラメーターには、0 または次の値の 1 つ以上を指定できます。
| 値 | 意味 |
|---|---|
|
ハードウェアが データ実行防止を強制する場合、このヒープから割り当てられたすべてのメモリ ブロックでコードの実行が許可されます。 ヒープからコードを実行するアプリケーションでは、このフラグ ヒープを使用します。 HEAP_CREATE_ENABLE_EXECUTEが指定されておらず、アプリケーションが保護されたページからコードを実行しようとすると、アプリケーションは状態コード STATUS_ACCESS_VIOLATIONで例外を受け取ります。 |
|
システムは、NULL を返す代わりに HeapAlloc と HeapReAlloc の呼び出しに対してエラー (メモリ不足状態など) を示す例外を発生させます。 |
|
シリアル化されたアクセスは、ヒープ関数がこのヒープにアクセスする場合には使用されません。 このオプションは、後続のすべてのヒープ関数呼び出しに適用されます。 または、個々のヒープ関数呼び出しでこのオプションを指定することもできます。
このオプションを使用して作成されたヒープに対して、断片化の少ないヒープ (LFH) を有効にすることはできません。 このオプションで作成されたヒープはロックできません。 シリアル化されたアクセスの詳細については、このトピックの「解説」セクションを参照してください。 |
[in] dwInitialSize
ヒープの初期サイズ (バイト単位)。 この値は、ヒープに対してコミットされるメモリの初期量を決定します。 値は、システム ページ サイズの倍数に切り上げられます。 値は dwMaximumSize より小さくする必要があります。
このパラメーターが 0 の場合、関数は 1 ページをコミットします。 ホスト コンピューター上のページのサイズを確認するには、 GetSystemInfo 関数を使用します。
[in] dwMaximumSize
ヒープの最大サイズ (バイト単位)。 HeapCreate 関数は、dwMaximumSize をシステム ページ サイズの倍数に切り上げ、そのサイズのブロックをヒープのプロセスの仮想アドレス空間に予約します。 HeapAlloc 関数または HeapReAlloc 関数によって行われた割り当て要求が dwInitialSize で指定されたサイズを超えた場合、システムはヒープの最大サイズまでヒープの追加のメモリ ページをコミットします。
dwMaximumSize が 0 でない場合、ヒープ サイズは固定され、最大サイズを超えることはできません。 また、ヒープから割り当てることができる最大のメモリ ブロックは、32 ビット プロセスでは 512 KB 未満、64 ビット プロセスでは 1,024 KB 未満です。 ヒープの最大サイズがブロックを格納するのに十分な大きさであっても、より大きなブロックを割り当てる要求は失敗します。
dwMaximumSize が 0 の場合、ヒープのサイズが大きくなる可能性があります。 ヒープのサイズは、使用可能なメモリによってのみ制限されます。 固定サイズ ヒープの制限を超えるメモリ ブロックを割り当てる要求は自動的に失敗しません。代わりに、システムは VirtualAlloc 関数を呼び出して、大きなブロックに必要なメモリを取得します。 大きなメモリ ブロックを割り当てる必要があるアプリケーションでは 、dwMaximumSize を 0 に設定する必要があります。
戻り値
関数が成功した場合、戻り値は新しく作成されたヒープへのハンドルです。
関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
HeapCreate 関数は、呼び出し元プロセスが HeapAlloc 関数を使用してメモリ ブロックを割り当てることができるプライベート ヒープ オブジェクトを作成します。 初期サイズは、ヒープに対して最初に割り当てられるコミット済みページの数を決定します。 最大サイズは、予約ページの合計数を決定します。 これらのページは、ヒープを拡張できるプロセスの仮想アドレス空間にブロックを作成します。 HeapAlloc による要求がコミットされたページの現在のサイズを超えた場合、物理ストレージが使用可能な場合、この予約領域から追加のページが自動的にコミットされます。
Windows Server 2003 および Windows XP: 既定では、新しく作成されたプライベート ヒープは標準ヒープです。 断片化の少ないヒープを有効にするには、プライベート ヒープへのハンドルを使用して HeapSetInformation 関数を呼び出します。
プライベート ヒープ オブジェクトのメモリには、それを作成したプロセスのみがアクセスできます。 ダイナミック リンク ライブラリ (DLL) によってプライベート ヒープが作成された場合、そのヒープは DLL を呼び出すプロセスのアドレス空間に作成され、そのプロセスのみがアクセスできます。
システムはプライベート ヒープのメモリを使用してヒープ サポート構造を格納するため、指定されたすべてのヒープ サイズをプロセスで使用できるわけではありません。 たとえば、 HeapAlloc 関数が最大サイズが 64K のヒープから 64 キロバイト (K) を要求した場合、システム オーバーヘッドが原因で要求が失敗する可能性があります。
HEAP_NO_SERIALIZEが指定されていない場合 (単純な既定値)、ヒープは呼び出しプロセス内でアクセスをシリアル化します。 シリアル化により、2 つ以上のスレッドが同時に同じヒープからブロックを割り当てたり解放したりしようとすると、相互の除外が保証されます。 シリアル化にはパフォーマンス コストは小さくなりますが、複数のスレッドが同じヒープからメモリを割り当てて解放するたびに使用する必要があります。 HeapLock 関数と HeapUnlock 関数を使用して、シリアル化されたヒープへのアクセスをブロックおよび許可できます。
HEAP_NO_SERIALIZEを設定すると、ヒープの相互除外がなくなります。 シリアル化を行わないと、同じヒープ ハンドルを使用する 2 つ以上のスレッドが同時にメモリの割り当てまたは解放を試みる可能性があり、ヒープが破損する可能性があります。 したがって、 HEAP_NO_SERIALIZE は、次の状況でのみ安全に使用できます。
- プロセスに含まれるスレッドは 1 つだけです。
- プロセスには複数のスレッドがありますが、特定のヒープのヒープ関数を呼び出すスレッドは 1 つだけです。
- プロセスには複数のスレッドがあり、アプリケーションは特定のヒープに対する相互除外のための独自のメカニズムを提供します。
heapLock 関数と HeapUnlock 関数が、HEAP_NO_SERIALIZE フラグを使用して作成されたヒープで呼び出された場合、結果は未定義になります。
プロセスの既定のヒープへのハンドルを取得するには、 GetProcessHeap 関数を使用します。 呼び出し元のプロセスでアクティブな既定のヒープとプライベート ヒープへのハンドルを取得するには、 GetProcessHeaps 関数を使用します。
例
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | heapapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |