Función HeapFree (heapapi.h)

Artículo
02/29/2024

Libera un bloque de memoria asignado desde un montón por la función HeapAlloc o HeapReAlloc .

Sintaxis

BOOL HeapFree(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem
);

Parámetros

[in] hHeap

Identificador del montón cuyo bloque de memoria se va a liberar. Este identificador lo devuelve la función HeapCreate o GetProcessHeap .

[in] dwFlags

Las opciones gratuitas del montón. Al especificar el siguiente valor, se invalida el valor correspondiente especificado en el parámetro flOptions cuando se creó el montón mediante la función HeapCreate .

Valor	Significado
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. No especifique este valor 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.

Valor

Significado

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.

No especifique este valor 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.

[in] lpMem

Puntero al bloque de memoria que se va a liberar. Este puntero lo devuelve la función HeapAlloc o HeapReAlloc . Este puntero puede ser NULL.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Una aplicación puede llamar a GetLastError para obtener información de error extendida.

Comentarios

No debe hacer referencia de ninguna manera a la memoria que ha liberado HeapFree. Después de liberar esa memoria, cualquier información que pueda haber estado en ella se ha ido para siempre. Si necesita información, no libere memoria que contenga la información. Es posible que las llamadas de función que devuelvan información sobre la memoria (como HeapSize) no se usen con memoria libre, ya que pueden devolver datos falsos. Llamar a HeapFree dos veces con el mismo puntero puede causar daños en el montón, lo que da lugar a llamadas posteriores a HeapAlloc que devuelven el mismo puntero dos veces.

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, consulte Obtención de montones de procesos.

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