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