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