HeapReAlloc 関数 (heapapi.h)

  • [アーティクル]

ヒープからメモリ ブロックを再割り当てします。 この関数を使用すると、メモリ ブロックのサイズを変更したり、他のメモリ ブロックのプロパティを変更したりできます。 割り当てられたメモリは移動できません。

構文

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

パラメーター

[in] hHeap

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

[in] dwFlags

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

値 意味
HEAP_GENERATE_EXCEPTIONS
0x00000004
 オペレーティング システムでは、 NULL を返す代わりに、メモリ不足状態などの関数エラーを示す例外が発生します。

この関数のすべての呼び出しに対して例外が確実に生成されるようにするには、HeapCreate の呼び出しで HEAP_GENERATE_EXCEPTIONSを指定します。 この場合、この関数呼び出しで HEAP_GENERATE_EXCEPTIONS を追加で指定する必要はありません。
HEAP_NO_SERIALIZE
0x00000001
 シリアル化されたアクセスは使用されません。 詳細については、「解説」を参照してください。

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

この値は、プロセス ヒープにアクセスするときに指定しないでください。 システムは、Ctrl + C ハンドラーなど、アプリケーションのプロセス内に、プロセス ヒープに同時にアクセスする追加のスレッドを作成できます。
HEAP_REALLOC_IN_PLACE_ONLY
0x00000010
 メモリ ブロックを再割り当てするときに移動することはできません。 この値を指定しない場合、関数はブロックを新しい場所に移動できます。 この値を指定し、移動せずにブロックのサイズを変更できない場合、関数は失敗し、元のメモリ ブロックは変更されません。
HEAP_ZERO_MEMORY
0x00000008
 再割り当て要求のサイズが大きい場合は、元のサイズを超える追加のメモリ領域が 0 に初期化されます。 元のサイズまでのメモリ ブロックの内容は影響を受けません。

[in] lpMem

関数が再割り当てするメモリ ブロックへのポインター。 このポインターは、HeapAlloc 関数または HeapReAlloc 関数の以前の呼び出しによって返されます。

[in] dwBytes

メモリ ブロックの新しいサイズ (バイト単位)。 メモリ ブロックのサイズは、この関数を使用して増減できます。

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

戻り値

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

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

関数が失敗し、 HEAP_GENERATE_EXCEPTIONS指定した場合、関数は次の表に示す例外のいずれかを生成する可能性があります。 詳細については、「 GetExceptionCode」を参照してください。

例外コード 説明
STATUS_NO_MEMORY 使用可能なメモリまたはヒープの破損がないため、割り当てが失敗しました。
STATUS_ACCESS_VIOLATION ヒープの破損または不適切な関数パラメーターが原因で割り当てが失敗しました。

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

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

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

注釈

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

HeapReAlloc が失敗した場合、元のメモリは解放されず、元のハンドルとポインターは引き続き有効です。

HeapReAlloc は、新しいメモリが別の場所に割り当てられている場合でも、再割り当てされるメモリの内容を保持することが保証されます。 メモリ コンテンツを保持するプロセスには、非常に時間がかかる可能性があるメモリ コピー操作が含まれます。

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

シリアル化により、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

関連項目

ヒープ関数

HeapAlloc

HeapFree

メモリ管理関数

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