Partager via


Fonction HeapReAlloc (heapapi.h)

Réalloue un bloc de mémoire à partir d’un tas. Cette fonction vous permet de redimensionner un bloc de mémoire et de modifier d’autres propriétés de bloc de mémoire. La mémoire allouée n’est pas mobile.

Syntaxe

DECLSPEC_ALLOCATOR LPVOID HeapReAlloc(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem,
  [in] SIZE_T                 dwBytes
);

Paramètres

[in] hHeap

Handle vers le tas à partir duquel la mémoire doit être réaffectée. Ce handle est un retourné par la fonction HeapCreate ou GetProcessHeap .

[in] dwFlags

Options de réaffectation du tas. La spécification d’une valeur remplace la valeur correspondante spécifiée dans le paramètre flOptions lors de la création du tas à l’aide de la fonction HeapCreate . Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur Signification
HEAP_GENERATE_EXCEPTIONS
0x00000004
Le système d’exploitation déclenche une exception pour indiquer un échec de fonction, tel qu’une condition de mémoire insuffisante, au lieu de retourner null.

Pour vous assurer que des exceptions sont générées pour tous les appels à cette fonction, spécifiez HEAP_GENERATE_EXCEPTIONS dans l’appel à HeapCreate. Dans ce cas, il n’est pas nécessaire de spécifier HEAP_GENERATE_EXCEPTIONS dans cet appel de fonction.

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

HEAP_REALLOC_IN_PLACE_ONLY
0x00000010
Il ne peut y avoir aucun mouvement lors de la réaffectation d’un bloc de mémoire. Si cette valeur n’est pas spécifiée, la fonction peut déplacer le bloc vers un nouvel emplacement. Si cette valeur est spécifiée et que le bloc ne peut pas être redimensionné sans déplacement, la fonction échoue, laissant le bloc de mémoire d’origine inchangé.
HEAP_ZERO_MEMORY
0x00000008
Si la demande de réallocation concerne une taille plus élevée, la région de mémoire supplémentaire au-delà de la taille d’origine est initialisée à zéro. Le contenu du bloc de mémoire jusqu’à sa taille d’origine n’est pas affecté.

[in] lpMem

Pointeur vers le bloc de mémoire que la fonction réalloue. Ce pointeur est retourné par un appel antérieur à la fonction HeapAlloc ou HeapReAlloc .

[in] dwBytes

Nouvelle taille du bloc de mémoire, en octets. La taille d’un bloc de mémoire peut être augmentée ou réduite à l’aide de cette fonction.

Si le tas spécifié par le paramètre hHeap est un tas « non extensible », dwBytes doit être inférieur à 0x7FFF8. Vous créez un tas non extensible en appelant la fonction HeapCreate avec une valeur différente de zéro.

Valeur retournée

Si la fonction réussit, la valeur de retour est un pointeur vers le bloc de mémoire réalloué.

Si la fonction échoue et que vous n’avez pas spécifié HEAP_GENERATE_EXCEPTIONS, la valeur de retour est NULL.

Si la fonction échoue et que vous avez spécifié HEAP_GENERATE_EXCEPTIONS, la fonction peut générer l’une des exceptions répertoriées dans le tableau suivant. Pour plus d’informations, consultez GetExceptionCode.

Code d'exception Description
STATUS_NO_MEMORY La tentative d’allocation a échoué en raison d’un manque de mémoire disponible ou d’une altération du tas.
STATUS_ACCESS_VIOLATION La tentative d’allocation a échoué en raison d’une altération du tas ou de paramètres de fonction incorrects.

L’alignement de la mémoire retournée par HeapReAlloc est MEMORY_ALLOCATION_ALIGNMENT dans WinNT.h :

#if defined(_WIN64) || defined(_M_ALPHA)
#define MEMORY_ALLOCATION_ALIGNMENT 16
#else
#define MEMORY_ALLOCATION_ALIGNMENT 8
#endif

Si la fonction échoue, elle n’appelle pas SetLastError. Une application ne peut pas appeler GetLastError pour obtenir des informations d’erreur étendues.

Remarques

Si HeapReAlloc réussit, il alloue au moins la quantité de mémoire demandée.

Si HeapReAlloc échoue, la mémoire d’origine n’est pas libérée, et le handle et le pointeur d’origine sont toujours valides.

HeapReAlloc est garanti pour conserver le contenu de la mémoire en cours de réallocation, même si la nouvelle mémoire est allouée à un autre emplacement. Le processus de conservation du contenu de la mémoire implique une opération de copie de la mémoire qui peut prendre beaucoup de temps.

Pour libérer un bloc de mémoire alloué par HeapReAlloc, utilisez la fonction HeapFree .

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

HeapAlloc

HeapFree

Fonctions de gestion de la mémoire

API Vertdll disponibles dans les enclaves VBS