Fonction HeapAlloc (heapapi.h)
Alloue un bloc de mémoire à partir d’un tas. La mémoire allouée n’est pas déplacée.
Syntaxe
DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
[in] HANDLE hHeap,
[in] DWORD dwFlags,
[in] SIZE_T dwBytes
);
Paramètres
[in] hHeap
Handle du tas à partir duquel la mémoire sera allouée. Ce handle est retourné par la fonction HeapCreate ou GetProcessHeap .
[in] dwFlags
Options d’allocation de tas. La spécification de l’une de ces valeurs remplace la valeur correspondante spécifiée lorsque le tas a été créé avec HeapCreate. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Le système déclenche une exception pour indiquer une défaillance de fonction, telle 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 cette allocation.
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. Cette valeur ne doit pas être spécifiée lors de l’accès au tas par défaut du 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 par défaut du processus. |
|
La mémoire allouée est initialisée à zéro. Sinon, la mémoire n’est pas initialisée à zéro. |
[in] dwBytes
Nombre d’octets à allouer.
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 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. L’exception particulière dépend de la nature de la corruption du tas. 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. |
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 la fonction HeapAlloc réussit, elle alloue au moins la quantité de mémoire demandée.
Pour allouer de la mémoire à partir du tas par défaut du processus, utilisez HeapAlloc avec le handle retourné par la fonction GetProcessHeap .
Pour libérer un bloc de mémoire alloué par HeapAlloc, utilisez la fonction HeapFree .
La mémoire allouée par HeapAlloc n’est pas mobile. L’adresse retournée par HeapAlloc est valide jusqu’à ce que le bloc de mémoire soit libéré ou réalloué ; le bloc de mémoire n’a pas besoin d’être verrouillé. Comme le système ne peut pas compacter un tas privé, il peut devenir fragmenté.
L’alignement de la mémoire retournée par HeapAlloc 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
Les applications qui allouent de grandes quantités de mémoire dans différentes tailles d’allocation peuvent utiliser le tas à faible fragmentation pour réduire la fragmentation du tas.
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 Exemple AWE.
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 |