Función HeapAlloc (heapapi.h)

Asigna un bloque de memoria de un montón. La memoria asignada no se puede mover.

Sintaxis

DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags,
  [in] SIZE_T dwBytes
);

Parámetros

[in] hHeap

Identificador del montón desde el que se asignará la memoria. La función HeapCreate o GetProcessHeap devuelve este identificador.

[in] dwFlags

Opciones de asignación del montón. Al especificar cualquiera de estos valores, se invalidará el valor correspondiente especificado cuando se creó el montón con HeapCreate. Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
HEAP_GENERATE_EXCEPTIONS 0x00000004	El sistema generará 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	El acceso serializado no se usará para esta asignación. 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 predeterminado del proceso. 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 predeterminado del proceso.
HEAP_ZERO_MEMORY 0x00000008	La memoria asignada se inicializará en cero. De lo contrario, la memoria no se inicializa en cero.

[in] dwBytes

Número de bytes que se van a asignar.

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 asignado.

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. La excepción determinada depende de la naturaleza de los daños en el montón. 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.

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 la función HeapAlloc se realiza correctamente, asigna al menos la cantidad de memoria solicitada.

Para asignar memoria del montón predeterminado del proceso, use HeapAlloc con el identificador devuelto por la función GetProcessHeap .

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

La memoria asignada por HeapAlloc no se puede mover. La dirección devuelta por HeapAlloc es válida hasta que el bloque de memoria se libera o se reasigna; no es necesario bloquear el bloque de memoria. Dado que el sistema no puede compactar un montón privado, se puede fragmentar.

La alineación de la memoria devuelta por HeapAlloc 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

Las aplicaciones que asignan grandes cantidades de memoria en varios tamaños de asignación pueden usar el montón de baja fragmentación para reducir la fragmentación del montón.

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.

Ejemplos

Para obtener un ejemplo, vea Ejemplo de AWE.

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

HeapFree

HeapReAlloc

Funciones de administración de memoria

API de Vertdll disponibles en enclaves de VBS