HeapFree, fonction (heapapi.h)

Article
02/26/2024

Libère un bloc de mémoire alloué à partir d’un tas par la fonction HeapAlloc ou HeapReAlloc .

Syntaxe

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

Paramètres

[in] hHeap

Handle du tas dont le bloc de mémoire doit être libéré. Ce handle est retourné par la fonction HeapCreate ou GetProcessHeap .

[in] dwFlags

Options libres de tas. La spécification de la valeur suivante remplace la valeur correspondante spécifiée dans le paramètre flOptions lorsque le tas a été créé à l’aide de la fonction HeapCreate .

Valeur	Signification
HEAP_NO_SERIALIZE 0x00000001	L’accès sérialisé ne sera pas utilisé. Pour plus d'informations, consultez la section Notes. Pour vous assurer que l’accès sérialisé est désactivé pour tous les appels à cette fonction, spécifiez HEAP_NO_SERIALIZE dans l’appel à HeapCreate. Dans ce cas, il n’est pas nécessaire de spécifier HEAP_NO_SERIALIZE dans cet appel de fonction. Ne spécifiez pas cette valeur lors de l’accès au tas de processus. Le système peut créer des threads supplémentaires dans le processus de l’application, tels qu’un gestionnaire CTRL+C, qui accèdent simultanément au tas de processus.

Valeur

Signification

HEAP_NO_SERIALIZE
0x00000001

L’accès sérialisé ne sera pas utilisé. Pour plus d'informations, consultez la section Notes.

Pour vous assurer que l’accès sérialisé est désactivé pour tous les appels à cette fonction, spécifiez HEAP_NO_SERIALIZE dans l’appel à HeapCreate. Dans ce cas, il n’est pas nécessaire de spécifier HEAP_NO_SERIALIZE dans cet appel de fonction.

Ne spécifiez pas cette valeur lors de l’accès au tas de processus. Le système peut créer des threads supplémentaires dans le processus de l’application, tels qu’un gestionnaire CTRL+C, qui accèdent simultanément au tas de processus.

[in] lpMem

Pointeur vers le bloc de mémoire à libérer. Ce pointeur est retourné par la fonction HeapAlloc ou HeapReAlloc . Ce pointeur peut avoir la valeur NULL.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Une application peut appeler GetLastError pour obtenir des informations d’erreur étendues.

Remarques

Vous ne devez en aucun cas faire référence à la mémoire libérée par HeapFree. Une fois que la mémoire est libérée, toutes les informations qui ont pu y être contenues disparaissent pour toujours. Si vous avez besoin d’informations, ne libérez pas la mémoire contenant les informations. Les appels de fonction qui retournent des informations sur la mémoire (comme HeapSize) ne peuvent pas être utilisés avec de la mémoire libérée, car ils peuvent retourner des données fausses. L’appel de HeapFree deux fois avec le même pointeur peut provoquer une altération du tas, ce qui entraîne des appels ultérieurs à HeapAlloc renvoyant le même pointeur deux fois.

La sérialisation garantit l’exclusion mutuelle lorsque deux threads ou plus tentent d’allouer ou de libérer simultanément des blocs à partir du même tas. Il existe un faible coût de performances pour la sérialisation, mais il doit être utilisé chaque fois que plusieurs threads allouent et libèrent de la mémoire du même tas. La définition de la valeur HEAP_NO_SERIALIZE élimine l’exclusion mutuelle sur le tas. Sans sérialisation, deux threads ou plus qui utilisent le même handle de tas peuvent tenter d’allouer ou de libérer de la mémoire simultanément, ce qui risque d’endommager le tas. La valeur HEAP_NO_SERIALIZE peut donc être utilisée en toute sécurité uniquement dans les situations suivantes :

Le processus n’a qu’un seul thread.
Le processus comporte plusieurs threads, mais un seul thread appelle les fonctions de tas pour un tas spécifique.
Le processus comporte plusieurs threads et l’application fournit son propre mécanisme d’exclusion mutuelle à un tas spécifique.

Exemples

Pour obtenir un exemple, consultez Obtention de tas de processus.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	heapapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll