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 매개 변수에 지정된 해당 값이 재정의됩니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값 의미
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를 참조하세요.

예외 코드 Description
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 함수를 사용합니다.

직렬화는 둘 이상의 스레드가 동일한 힙에서 블록을 동시에 할당하거나 해제하려고 할 때 상호 제외를 보장합니다. serialization에는 약간의 성능 비용이 있지만 여러 스레드가 동일한 힙에서 메모리를 할당하고 해제할 때마다 사용해야 합니다. HEAP_NO_SERIALIZE 값을 설정하면 힙에서 상호 제외가 제거됩니다. 직렬화가 없으면 동일한 힙 핸들을 사용하는 두 개 이상의 스레드가 동시에 메모리를 할당하거나 해제하려고 시도할 수 있으며, 이로 인해 힙이 손상될 수 있습니다. 따라서 HEAP_NO_SERIALIZE 값은 다음과 같은 경우에만 안전하게 사용할 수 있습니다.

  • 프로세스에는 스레드가 하나만 있습니다.
  • 프로세스에는 여러 스레드가 있지만 한 스레드만 특정 힙에 대한 힙 함수를 호출합니다.
  • 프로세스에는 여러 스레드가 있으며 애플리케이션은 특정 힙에 대한 상호 배제를 위한 고유한 메커니즘을 제공합니다.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows XP [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 heapapi.h(Windows.h 포함)
라이브러리 Kernel32.lib
DLL Kernel32.dll

참고 항목

힙 함수

HeapAlloc

HeapFree

메모리 관리 함수

VBS Enclave에서 사용할 수 있는 Vertdll API