Fonction HeapCompact (heapapi.h)

  • Article

Retourne la taille du plus grand bloc libre validé dans le tas spécifié. Si l’indicateur Désactiver la coalesce du tas sur free global est défini, cette fonction fusionne également les blocs de mémoire libres adjacents dans le tas.

Syntaxe

SIZE_T HeapCompact(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags
);

Paramètres

[in] hHeap

Une poignée au tas. Ce handle est retourné par la fonction HeapCreate ou GetProcessHeap .

[in] dwFlags

Options d’accès au tas. Ce paramètre peut être la valeur suivante.

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 retournée

Si la fonction réussit, la valeur de retour est la taille du plus grand bloc libre validé dans le tas, en octets.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Dans le cas peu probable où il n’y a absolument aucun espace disponible dans le tas, la valeur de retour de la fonction est zéro et GetLastError retourne la valeur NO_ERROR.

Remarques

La fonction HeapCompact est principalement utile pour le débogage. En règle générale, le système compacte le tas chaque fois que la fonction HeapFree est appelée, et la fonction HeapCompact retourne la taille du plus grand bloc libre du tas, mais ne compacte plus le tas. Si l’indicateur Désactiver la fusion du tas sur free global est défini pendant le débogage, le système ne compacte pas le tas et l’appel de la fonction HeapCompact compacte le tas. Pour plus d’informations sur les indicateurs globaux, consultez la documentation GFlags .

Il n’est pas garanti qu’une application puisse allouer correctement un bloc de mémoire de la taille retournée par HeapCompact. D’autres threads ou le seuil de validation peuvent empêcher une telle allocation.

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.

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

Voir aussi

Fonctions de tas

TasCréer

HeapValidate

Fonctions de gestion de la mémoire

API Vertdll disponibles dans les enclaves VBS