Funzione HeapCreate (heapapi.h)
Crea un oggetto heap privato che può essere usato dal processo di chiamata. La funzione riserva spazio nello spazio indirizzi virtuale del processo e alloca l'archiviazione fisica per una parte iniziale specificata di questo blocco.
Sintassi
HANDLE HeapCreate(
[in] DWORD flOptions,
[in] SIZE_T dwInitialSize,
[in] SIZE_T dwMaximumSize
);
Parametri
[in] flOptions
Opzioni di allocazione dell'heap. Queste opzioni influiscono sull'accesso successivo al nuovo heap tramite chiamate alle funzioni heap. Questo parametro può essere 0 o uno o più dei valori seguenti.
| Valore | Significato |
|---|---|
|
Tutti i blocchi di memoria allocati da questo heap consentono l'esecuzione del codice, se l'hardware applica la prevenzione dell'esecuzione dei dati. Usare questo heap flag nelle applicazioni che eseguono codice dall'heap. Se HEAP_CREATE_ENABLE_EXECUTE non è specificato e un'applicazione tenta di eseguire codice da una pagina protetta, l'applicazione riceve un'eccezione con il codice di stato STATUS_ACCESS_VIOLATION. |
|
Il sistema genera un'eccezione per indicare un errore (ad esempio, una condizione di memoria insufficiente) per le chiamate a HeapAlloc e HeapReAlloc anziché restituire NULL. |
|
L'accesso serializzato non viene usato quando le funzioni heap accedono a questo heap. Questa opzione si applica a tutte le chiamate di funzione heap successive. In alternativa, è possibile specificare questa opzione in singole chiamate di funzione heap.
Impossibile abilitare l'heap a frammentazione bassa (LFH) per un heap creato con questa opzione. Impossibile bloccare un heap creato con questa opzione. Per altre informazioni sull'accesso serializzato, vedere la sezione Osservazioni di questo argomento. |
[in] dwInitialSize
Dimensioni iniziali dell'heap, in byte. Questo valore determina la quantità iniziale di memoria di cui viene eseguito il commit per l'heap. Il valore viene arrotondato a più dimensioni della pagina di sistema. Il valore deve essere minore di dwMaximumSize.
Se questo parametro è 0, la funzione esegue il commit di una pagina. Per determinare le dimensioni di una pagina nel computer host, usare la funzione GetSystemInfo .
[in] dwMaximumSize
Dimensione massima dell'heap, in byte. La funzione HeapCreate arrotonda dwMaximumSize fino a un multiplo delle dimensioni della pagina di sistema e quindi riserva un blocco di tale dimensione nello spazio indirizzi virtuale del processo per l'heap. Se le richieste di allocazione effettuate dalle funzioni HeapAlloc o HeapReAlloc superano le dimensioni specificate da dwInitialSize, il sistema esegue il commit di pagine aggiuntive di memoria per l'heap, fino alle dimensioni massime dell'heap.
Se dwMaximumSize non è zero, le dimensioni dell'heap sono fisse e non possono crescere oltre le dimensioni massime. Inoltre, il blocco di memoria più grande che può essere allocato dall'heap è leggermente inferiore a 512 KB per un processo a 32 bit e leggermente inferiore a 1.024 KB per un processo a 64 bit. Le richieste di allocare blocchi più grandi hanno esito negativo, anche se la dimensione massima dell'heap è sufficiente per contenere il blocco.
Se dwMaximumSize è 0, l'heap può crescere di dimensioni. Le dimensioni dell'heap sono limitate solo dalla memoria disponibile. Le richieste per allocare blocchi di memoria superiori al limite per un heap di dimensioni fisse non hanno esito negativo automaticamente; il sistema chiama invece la funzione VirtualAlloc per ottenere la memoria necessaria per blocchi di grandi dimensioni. Le applicazioni che devono allocare blocchi di memoria di grandi dimensioni devono impostare dwMaximumSize su 0.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per l'heap appena creato.
Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
La funzione HeapCreate crea un oggetto heap privato da cui il processo chiamante può allocare blocchi di memoria usando la funzione HeapAlloc . Le dimensioni iniziali determinano il numero di pagine di commit allocate inizialmente per l'heap. La dimensione massima determina il numero totale di pagine riservate. Queste pagine creano un blocco nello spazio indirizzi virtuale del processo in cui l'heap può crescere. Se le richieste di HeapAlloc superano le dimensioni correnti delle pagine di commit, le pagine aggiuntive vengono eseguite automaticamente da questo spazio riservato, se la risorsa di archiviazione fisica è disponibile.
Windows Server 2003 e Windows XP: Per impostazione predefinita, l'heap privato appena creato è un heap standard. Per abilitare l'heap a frammentazione ridotta, chiamare la funzione HeapSetInformation con un handle nell'heap privato.
La memoria di un oggetto heap privato è accessibile solo al processo creato. Se una libreria di collegamento dinamico (DLL) crea un heap privato, l'heap viene creato nello spazio indirizzi del processo che chiama la DLL ed è accessibile solo per tale processo.
Il sistema usa la memoria dall'heap privato per archiviare strutture di supporto heap, quindi non tutte le dimensioni dell'heap specificate sono disponibili per il processo. Ad esempio, se la funzione HeapAlloc richiede 64 kilobyte (K) da un heap con dimensioni massime di 64K, la richiesta potrebbe non riuscire a causa del sovraccarico del sistema.
Se HEAP_NO_SERIALIZE non è specificato (impostazione predefinita semplice), l'heap serializza l'accesso all'interno del processo chiamante. La serializzazione garantisce l'esclusione reciproca quando due o più thread tentano simultaneamente di allocare o liberare blocchi dallo stesso heap. È previsto un costo di prestazioni ridotto per la serializzazione, ma deve essere usato ogni volta che più thread allocano e liberano memoria dallo stesso heap. Le funzioni HeapLock e HeapUnlock possono essere usate per bloccare e consentire l'accesso a un heap serializzato.
L'impostazione HEAP_NO_SERIALIZE elimina l'esclusione reciproca nell'heap. Senza serializzazione, due o più thread che usano lo stesso handle heap potrebbero tentare di allocare o liberare memoria contemporaneamente, che può causare danneggiamento nell'heap. Pertanto, HEAP_NO_SERIALIZE può essere usato in modo sicuro solo nelle situazioni seguenti:
- Il processo ha un solo thread.
- Il processo include più thread, ma solo un thread chiama le funzioni heap per un heap specifico.
- Il processo include più thread e l'applicazione fornisce il proprio meccanismo per l'esclusione reciproca a un heap specifico.
Se le funzioni HeapLock e HeapUnlock vengono chiamate su un heap creato con il flag HEAP_NO_SERIALIZE , i risultati non sono definiti.
Per ottenere un handle per l'heap predefinito per un processo, usare la funzione GetProcessHeap . Per ottenere handle all'heap predefinito e agli heaps privati attivi per il processo chiamante, usare la funzione GetProcessHeaps .
Esempio
Requisiti
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | heapapi.h (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |