HeapValidate, fonction (heapapi.h)

  • Article

Valide le tas spécifié. La fonction analyse tous les blocs de mémoire dans le tas et vérifie que les structures de contrôle de tas gérées par le gestionnaire de tas sont dans un état cohérent. Vous pouvez également utiliser la fonction HeapValidate pour valider un bloc de mémoire unique dans un tas spécifié sans vérifier la validité du tas entier.

Syntaxe

BOOL HeapValidate(
  [in]           HANDLE  hHeap,
  [in]           DWORD   dwFlags,
  [in, optional] LPCVOID lpMem
);

Paramètres

[in] hHeap

Handle du tas à valider. 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 davantage HEAP_NO_SERIALIZE dans cet appel de fonction.

Cette valeur ne doit pas être spécifiée lors de l’accès au tas de processus par défaut. 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 par défaut.

[in, optional] lpMem

Pointeur vers un bloc de mémoire dans le tas spécifié. Ce paramètre peut être NULL.

Si ce paramètre a la valeur NULL, la fonction tente de valider l’intégralité du tas spécifié par hHeap.

Si ce paramètre n’est pas NULL, la fonction tente de valider le bloc de mémoire pointé par lpMem. Il ne tente pas de valider le reste du tas.

Valeur retournée

Si le segment de mémoire ou le bloc de mémoire spécifié est valide, la valeur de retour est différente de zéro.

Si le segment de mémoire ou le bloc de mémoire spécifié n’est pas valide, la valeur de retour est zéro. Sur un système configuré pour le débogage, la fonction HeapValidate affiche ensuite les messages de débogage qui décrivent la partie du tas ou du bloc de mémoire non valide, et s’arrête à un point d’arrêt codé en dur afin que vous puissiez examiner le système pour déterminer la source de l’invalidité. La fonction HeapValidate ne définit pas la dernière valeur d’erreur du thread. Il n’existe aucune information d’erreur étendue pour cette fonction ; n’appelez pas GetLastError.

Remarques

La fonction HeapValidate est principalement utile pour le débogage, car la validation peut prendre du temps. La validation d’un tas peut empêcher d’autres threads d’accéder au tas et peut dégrader les performances, en particulier sur les ordinateurs multitraitement symétriques (SMP). Ces effets secondaires peuvent durer jusqu’au retour de HeapValidate .

Il existe des structures de contrôle de tas pour chaque bloc de mémoire dans un tas et pour le tas dans son ensemble. Lorsque vous utilisez la fonction HeapValidate pour valider un tas complet, elle vérifie la cohérence de toutes ces structures de contrôle.

Lorsque vous utilisez HeapValidate pour valider un seul bloc de mémoire dans un tas, il vérifie uniquement les structures de contrôle relatives à cet élément. HeapValidate peut uniquement valider les blocs de mémoire alloués. L’appel de HeapValidate sur un bloc de mémoire libéré retourne FALSE , car il n’existe aucune structure de contrôle à valider.

Si vous souhaitez valider les éléments de tas énumérés par la fonction HeapWalk , vous devez appeler HeapValidate uniquement sur les éléments qui ont PROCESS_HEAP_ENTRY_BUSY dans le membre wFlags de la structure PROCESS_HEAP_ENTRY . HeapValidate retourne FALSE pour tous les éléments de tas qui n’ont pas ce bit défini.

La sérialisation garantit l’exclusion mutuelle lorsque deux ou plusieurs threads tentent d’allouer simultanément ou de libérer des blocs du même tas. La sérialisation coûte peu de performances, mais elle doit être utilisée 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 uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
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

HeapWalk

Fonctions de gestion de la mémoire

PROCESS_HEAP_ENTRY