HeapCompact 関数 (heapapi.h)

  • [アーティクル]

指定したヒープ内の最大コミット済みフリー ブロックのサイズを返します。 [空きグローバル フラグでヒープ結合を無効にする] フラグが設定されている場合、この関数はヒープ内の隣接する空きメモリ ブロックも結合します。

構文

SIZE_T HeapCompact(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags
);

パラメーター

[in] hHeap

ヒープへのハンドル。 このハンドルは、 HeapCreate 関数または GetProcessHeap 関数によって返されます。

[in] dwFlags

ヒープ アクセス オプション。 このパラメーターには、次の値を指定できます。

値 意味
HEAP_NO_SERIALIZE
0x00000001
 シリアル化されたアクセスは使用されません。

詳細については、「解説」を参照してください。

この関数のすべての呼び出しでシリアル化されたアクセスが無効になっていることを確認するには、HeapCreate の呼び出しで HEAP_NO_SERIALIZE を指定します。 この場合、この関数呼び出しで HEAP_NO_SERIALIZE をさらに指定する必要はありません。

プロセス ヒープにアクセスするときは、この値を指定しないでください。 システムは、アプリケーションのプロセス内に、プロセス ヒープに同時にアクセスする追加のスレッド (Ctrl + C ハンドラーなど) を作成する場合があります。

戻り値

関数が成功した場合、戻り値はヒープ内で最大のコミット済みフリー ブロックのサイズ (バイト単位) です。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

ヒープに空き領域がまったく存在しない場合、関数の戻り値は 0 で、 GetLastError は NO_ERROR値を返します。

注釈

HeapCompact 関数は、主にデバッグに役立ちます。 通常、 HeapFree 関数が呼び出されるたびにシステムによってヒープが圧縮され、 HeapCompact 関数はヒープ内で最大の空きブロックのサイズを返しますが、ヒープをさらに圧縮することはありません。 デバッグ中 に [空きグローバルでヒープ結合を無効にする ] フラグが設定されている場合、システムはヒープを圧縮せず、 HeapCompact 関数を呼び出すとヒープが圧縮されます。 グローバル フラグの詳細については、 GFlags のドキュメントを参照してください。

HeapCompact によって返されるサイズのメモリ ブロックをアプリケーションが正常に割り当てることができるという保証はありません。 他のスレッドまたはコミットのしきい値によって、このような割り当てが妨げる可能性があります。

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

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

要件

要件 値
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー heapapi.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

ヒープ関数

HeapCreate

HeapValidate

メモリ管理関数

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