HeapCreate, fonction (heapapi.h)
Crée un objet tas privé qui peut être utilisé par le processus appelant. La fonction réserve de l’espace dans l’espace d’adressage virtuel du processus et alloue du stockage physique pour une partie initiale spécifiée de ce bloc.
Syntaxe
HANDLE HeapCreate(
[in] DWORD flOptions,
[in] SIZE_T dwInitialSize,
[in] SIZE_T dwMaximumSize
);
Paramètres
[in] flOptions
Options d’allocation de tas. Ces options affectent l’accès ultérieur au nouveau tas par le biais d’appels aux fonctions de tas. Ce paramètre peut être égal à 0 ou à une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Tous les blocs de mémoire alloués à partir de ce tas autorisent l’exécution du code, si le matériel applique une prévention de l’exécution des données. Utilisez ce tas d’indicateur dans les applications qui exécutent du code à partir du tas. Si HEAP_CREATE_ENABLE_EXECUTE n’est pas spécifié et qu’une application tente d’exécuter du code à partir d’une page protégée, l’application reçoit une exception avec le code status STATUS_ACCESS_VIOLATION. |
|
Le système lève une exception pour indiquer un échec (par exemple, une condition de mémoire insuffisante) pour les appels à HeapAlloc et HeapReAlloc au lieu de retourner NULL. |
|
L’accès sérialisé n’est pas utilisé lorsque les fonctions de tas accèdent à ce tas. Cette option s’applique à tous les appels de fonction tas suivants. Vous pouvez également spécifier cette option sur les appels de fonction de tas individuels.
Le tas à faible fragmentation (LFH) ne peut pas être activé pour un tas créé avec cette option. Un tas créé avec cette option ne peut pas être verrouillé. Pour plus d’informations sur l’accès sérialisé, consultez la section Remarques de cette rubrique. |
[in] dwInitialSize
Taille initiale du tas, en octets. Cette valeur détermine la quantité initiale de mémoire validée pour le tas. La valeur est arrondie à un multiple de la taille de page système. La valeur doit être inférieure à dwMaximumSize.
Si ce paramètre a la valeur 0, la fonction valide une page. Pour déterminer la taille d’une page sur l’ordinateur hôte, utilisez la fonction GetSystemInfo .
[in] dwMaximumSize
Taille maximale du tas, en octets. La fonction HeapCreate arrondit dwMaximumSize à un multiple de la taille de page système, puis réserve un bloc de cette taille dans l’espace d’adressage virtuel du processus pour le tas. Si les demandes d’allocation effectuées par les fonctions HeapAlloc ou HeapReAlloc dépassent la taille spécifiée par dwInitialSize, le système valide des pages de mémoire supplémentaires pour le tas, jusqu’à la taille maximale du tas.
Si dwMaximumSize n’est pas égal à zéro, la taille du tas est fixe et ne peut pas dépasser la taille maximale. En outre, le plus grand bloc de mémoire qui peut être alloué à partir du tas est légèrement inférieur à 512 Ko pour un processus 32 bits et un peu moins de 1 024 Ko pour un processus 64 bits. Les demandes d’allocation de blocs plus grands échouent, même si la taille maximale du tas est suffisamment grande pour contenir le bloc.
Si dwMaximumSize a la valeur 0, le tas peut augmenter en taille. La taille du tas est limitée uniquement par la mémoire disponible. Les demandes d’allocation de blocs de mémoire supérieurs à la limite d’un tas de taille fixe n’échouent pas automatiquement ; au lieu de cela, le système appelle la fonction VirtualAlloc pour obtenir la mémoire nécessaire pour les blocs volumineux. Les applications qui doivent allouer des blocs de mémoire volumineux doivent définir dwMaximumSize sur 0.
Valeur retournée
Si la fonction réussit, la valeur de retour est un handle pour le tas nouvellement créé.
Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Remarques
La fonction HeapCreate crée un objet de tas privé à partir duquel le processus appelant peut allouer des blocs de mémoire à l’aide de la fonction HeapAlloc . La taille initiale détermine le nombre de pages validées qui sont allouées initialement pour le tas. La taille maximale détermine le nombre total de pages réservées. Ces pages créent un bloc dans l’espace d’adressage virtuel du processus dans lequel le tas peut croître. Si les demandes de HeapAlloc dépassent la taille actuelle des pages validées, des pages supplémentaires sont automatiquement validées à partir de cet espace réservé, si le stockage physique est disponible.
Windows Server 2003 et Windows XP : Par défaut, le tas privé nouvellement créé est un tas standard. Pour activer le tas à faible fragmentation, appelez la fonction HeapSetInformation avec un handle vers le tas privé.
La mémoire d’un objet tas privé est accessible uniquement au processus qui l’a créé. Si une bibliothèque de liens dynamiques (DLL) crée un tas privé, le tas est créé dans l’espace d’adressage du processus qui appelle la DLL, et il est accessible uniquement à ce processus.
Le système utilise la mémoire du tas privé pour stocker les structures de prise en charge du tas, de sorte que toutes les tailles de tas spécifiées ne sont pas disponibles pour le processus. Par exemple, si la fonction HeapAlloc demande 64 kilo-octets (K) à partir d’un tas d’une taille maximale de 64 Ko, la requête peut échouer en raison de la surcharge du système.
Si HEAP_NO_SERIALIZE n’est pas spécifié (valeur par défaut simple), le tas sérialise l’accès au sein du processus appelant. La sérialisation garantit l’exclusion mutuelle lorsque deux threads ou plus tentent simultanément d’allouer 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. Les fonctions HeapLock et HeapUnlock peuvent être utilisées pour bloquer et autoriser l’accès à un tas sérialisé.
La définition 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 peut provoquer une altération dans le tas. Par conséquent, HEAP_NO_SERIALIZE ne peut être utilisé en toute sécurité que 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.
Si les fonctions HeapLock et HeapUnlock sont appelées sur un tas créé avec l’indicateur HEAP_NO_SERIALIZE , les résultats ne sont pas définis.
Pour obtenir un handle pour le tas par défaut d’un processus, utilisez la fonction GetProcessHeap . Pour obtenir les handles du tas par défaut et des tas privés actifs pour le processus appelant, utilisez la fonction GetProcessHeaps .
Exemples
Configuration requise
| 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 |