Función HeapReAlloc (heapapi.h)

  • Artículo

Reasigna un bloque de memoria de un montón. Esta función permite cambiar el tamaño de un bloque de memoria y cambiar otras propiedades de bloque de memoria. La memoria asignada no se puede mover.

Sintaxis

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

Parámetros

[in] hHeap

Identificador del montón desde el que se va a reasignar la memoria. Este identificador es devuelto por la función HeapCreate o GetProcessHeap .

[in] dwFlags

Las opciones de reasignación del montón. Al especificar un valor, se invalida el valor correspondiente especificado en el parámetro flOptions cuando se creó el montón mediante la función HeapCreate . Este parámetro puede ser uno o más de los siguientes valores.

Valor Significado
HEAP_GENERATE_EXCEPTIONS
0x00000004
 El sistema operativo genera una excepción para indicar un error de función, como una condición de memoria insuficiente, en lugar de devolver NULL.

Para asegurarse de que se generan excepciones para todas las llamadas a esta función, especifique HEAP_GENERATE_EXCEPTIONS en la llamada a HeapCreate. En este caso, no es necesario especificar además HEAP_GENERATE_EXCEPTIONS en esta llamada de función.
HEAP_NO_SERIALIZE
0x00000001
 No se usará el acceso serializado. Para obtener más información, vea la sección Comentarios.

Para asegurarse de que el acceso serializado está deshabilitado para todas las llamadas a esta función, especifique HEAP_NO_SERIALIZE en la llamada a HeapCreate. En este caso, no es necesario especificar además HEAP_NO_SERIALIZE en esta llamada de función.

Este valor no se debe especificar al acceder al montón de procesos. El sistema puede crear subprocesos adicionales dentro del proceso de la aplicación, como un controlador CTRL+C, que accede simultáneamente al montón del proceso.
HEAP_REALLOC_IN_PLACE_ONLY
0x00000010
 No puede haber movimiento al reasignar un bloque de memoria. Si no se especifica este valor, la función puede mover el bloque a una nueva ubicación. Si se especifica este valor y no se puede cambiar el tamaño del bloque sin mover, se produce un error en la función, dejando sin cambios el bloque de memoria original.
HEAP_ZERO_MEMORY
0x00000008
 Si la solicitud de reasignación es para un tamaño mayor, la región adicional de memoria más allá del tamaño original se inicializa en cero. El contenido del bloque de memoria hasta su tamaño original no se ve afectado.

[in] lpMem

Puntero al bloque de memoria que la función reasigna. Este puntero lo devuelve una llamada anterior a la función HeapAlloc o HeapReAlloc .

[in] dwBytes

Nuevo tamaño del bloque de memoria, en bytes. El tamaño de un bloque de memoria se puede aumentar o disminuir mediante esta función.

Si el montón especificado por el parámetro hHeap es un montón "no cultivable", dwBytes debe ser menor que 0x7FFF8. Para crear un montón no cultivable, llame a la función HeapCreate con un valor distinto de cero.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un puntero al bloque de memoria reasignado.

Si se produce un error en la función y no se ha especificado HEAP_GENERATE_EXCEPTIONS, el valor devuelto es NULL.

Si se produce un error en la función y ha especificado HEAP_GENERATE_EXCEPTIONS, la función puede generar cualquiera de las excepciones enumeradas en la tabla siguiente. Para obtener más información, vea GetExceptionCode.

Código de excepción Descripción
STATUS_NO_MEMORY Error en el intento de asignación debido a la falta de memoria disponible o daños en el montón.
STATUS_ACCESS_VIOLATION Error en el intento de asignación debido a daños en el montón o parámetros de función incorrectos.

La alineación de la memoria devuelta por HeapReAlloc se MEMORY_ALLOCATION_ALIGNMENT en WinNT.h:

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

Si se produce un error en la función, no llama a SetLastError. Una aplicación no puede llamar a GetLastError para obtener información de error extendida.

Comentarios

Si HeapReAlloc se realiza correctamente, asigna al menos la cantidad de memoria solicitada.

Si se produce un error en HeapReAlloc , la memoria original no se libera y el identificador y el puntero originales siguen siendo válidos.

Se garantiza que HeapReAlloc conserve el contenido de la memoria que se reasigna, incluso si la nueva memoria se asigna en una ubicación diferente. El proceso de conservación del contenido de la memoria implica una operación de copia de memoria que puede llevar mucho tiempo.

Para liberar un bloque de memoria asignado por HeapReAlloc, use la función HeapFree .

La serialización garantiza la exclusión mutua cuando dos o más subprocesos intentan asignar o liberar bloques simultáneamente del mismo montón. Hay un pequeño costo de rendimiento para la serialización, pero debe usarse siempre que varios subprocesos asignen y liberen memoria del mismo montón. Establecer el valor de HEAP_NO_SERIALIZE elimina la exclusión mutua en el montón. Sin serialización, dos o más subprocesos que usan el mismo identificador de montón podrían intentar asignar o liberar memoria simultáneamente, lo que probablemente causaría daños en el montón. Por lo tanto, el valor de HEAP_NO_SERIALIZE solo se puede usar de forma segura en las situaciones siguientes:

  • El proceso solo tiene un subproceso.
  • El proceso tiene varios subprocesos, pero solo un subproceso llama a las funciones del montón para un montón específico.
  • El proceso tiene varios subprocesos y la aplicación proporciona su propio mecanismo para la exclusión mutua a un montón específico.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado heapapi.h (incluye Windows.h)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

Funciones del montón

HeapAlloc

HeapFree

Funciones de administración de memoria

API de Vertdll disponibles en enclaves de VBS