Funzione CreateIoCompletionPort
Crea una porta di completamento di input/output (I/O) e la associa a un handle di file specificato oppure crea una porta di completamento di I/O non ancora associata a un handle di file, consentendo l'associazione in un secondo momento.
L'associazione di un'istanza di un handle di file aperto a una porta di completamento di I/O consente a un processo di ricevere una notifica del completamento delle operazioni di I/O asincrone che coinvolgono tale handle di file.
Nota
Il termine handle di file usato qui fa riferimento a un'astrazione di sistema che rappresenta un endpoint di I/O sovrapposto, non solo un file su disco. Tutti gli oggetti di sistema che supportano operazioni di I/O sovrapposte, ad esempio endpoint di rete, socket TCP, named pipe e slot di posta elettronica, possono essere usati come handle di file. Per altre informazioni, vedere la sezione Osservazioni.
Sintassi
HANDLE WINAPI CreateIoCompletionPort(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE ExistingCompletionPort,
_In_ ULONG_PTR CompletionKey,
_In_ DWORD NumberOfConcurrentThreads
);
Parametri
-
FileHandle [in]
-
Handle o INVALID_HANDLE_VALUE di file aperti.
L'handle deve essere a un oggetto che supporta operazioni di I/O sovrapposte.
Se viene fornito un handle, deve essere stato aperto per il completamento di I/O sovrapposto. Ad esempio, è necessario specificare il flag FILE_FLAG_OVERLAPPED quando si usa la funzione CreateFile per ottenere l'handle.
Se viene specificato INVALID_HANDLE_VALUE , la funzione crea una porta di completamento I/O senza associarla a un handle di file. In questo caso, il parametro ExistingCompletionPort deve essere NULL e il parametro CompletionKey viene ignorato.
-
ExistingCompletionPort [in, facoltativo]
-
Handle per una porta di completamento I/O esistente o NULL.
Se questo parametro specifica una porta di completamento I/O esistente, la funzione la associa all'handle specificato dal parametro FileHandle . Se la funzione ha esito positivo, la funzione restituisce l'handle della porta di completamento I/O esistente; non crea una nuova porta di completamento di I/O.
Se questo parametro è NULL, la funzione crea una nuova porta di completamento I/O e, se il parametro FileHandle è valido, lo associa alla nuova porta di completamento di I/O. In caso contrario, non si verifica alcuna associazione di handle di file. Se ha esito positivo, la funzione restituisce l'handle alla nuova porta di completamento di I/O.
-
CompletionKey [in]
-
Chiave di completamento definita dall'utente per handle inclusa in ogni pacchetto di completamento di I/O per l'handle di file specificato. Per altre informazioni, vedere la sezione Osservazioni.
-
NumberOfConcurrentThreads [in]
-
Numero massimo di thread che il sistema operativo può consentire di elaborare simultaneamente i pacchetti di completamento di I/O per la porta di completamento di I/O. Questo parametro viene ignorato se il parametro ExistingCompletionPort non è NULL.
Se questo parametro è zero, il sistema consente il numero di thread in esecuzione simultanei in presenza di processori nel sistema.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è l'handle per una porta di completamento di I/O:
Se il parametro ExistingCompletionPort è NULL, il valore restituito è un nuovo handle.
Se il parametro ExistingCompletionPort è un handle di porta di completamento I/O valido, il valore restituito è lo stesso handle.
Se il parametro FileHandle è un handle valido, tale handle di file è ora associato alla porta di completamento di I/O restituita.
Se la funzione ha esito negativo, il valore restituito è NULL. Per ottenere informazioni sull'errore estese, chiamare la funzione GetLastError .
Commenti
È possibile invitare il sistema di I/O a inviare pacchetti di notifica di completamento I/O alle porte di completamento di I/O, in cui sono in coda. La funzione CreateIoCompletionPort fornisce questa funzionalità.
Una porta di completamento di I/O e il relativo handle sono associati al processo che lo ha creato e non è condivisibile tra i processi. Tuttavia, un singolo handle è condivisibile tra thread nello stesso processo.
CreateIoCompletionPort può essere usato in tre modalità distinte:
- Creare solo una porta di completamento I/O senza associarla a un handle di file.
- Associare una porta di completamento I/O esistente a un handle di file.
- Eseguire sia la creazione che l'associazione in una singola chiamata.
Per creare una porta di completamento I/O senza associarla, impostare il parametro FileHandle su INVALID_HANDLE_VALUE, il parametro ExistingCompletionPort su NULL e il parametro CompletionKey su zero (che viene ignorato in questo caso). Impostare il parametro NumberOfConcurrentThreads sul valore di concorrenza desiderato per la nuova porta di completamento di I/O oppure zero per il valore predefinito (il numero di processori nel sistema).
L'handle passato nel parametro FileHandle può essere qualsiasi handle che supporta operazioni di I/O sovrapposte. In genere, si tratta di un handle aperto dalla funzione CreateFile usando il flag FILE_FLAG_OVERLAPPED (ad esempio file, slot di posta elettronica e pipe). Anche gli oggetti creati da altre funzioni, ad esempio socket , possono essere associati a una porta di completamento di I/O. Per un esempio di uso dei socket, vedere AcceptEx. Un handle può essere associato a una sola porta di completamento di I/O e, dopo la creazione dell'associazione, l'handle rimane associato alla porta di completamento di I/O fino alla chiusura.
Per altre informazioni sulla teoria delle porte di completamento I/O, sull'utilizzo e sulle funzioni associate, vedere Porte di completamento I/O.
È possibile associare più handle di file a una singola porta di completamento I/O chiamando CreateIoCompletionPort più volte con lo stesso handle di porta di completamento I/O nel parametro ExistingCompletionPort e un handle di file diverso nel parametro FileHandle ogni volta.
Usare il parametro CompletionKey per tenere traccia delle operazioni di I/O completate dall'applicazione. Questo valore non viene usato da CreateIoCompletionPort per il controllo funzionale; viene invece collegato all'handle di file specificato nel parametro FileHandle al momento dell'associazione con una porta di completamento I/O. Questa chiave di completamento deve essere univoca per ogni handle di file e accompagna l'handle di file durante il processo di accodamento interno. Viene restituito nella chiamata alla funzione GetQueuedCompletionStatus quando arriva un pacchetto di completamento. Il parametro CompletionKey viene usato anche dalla funzione PostQueuedCompletionStatus per accodare i pacchetti di completamento specifici.
Dopo che un'istanza di un handle aperto è associata a una porta di completamento I/O, non può essere usata nella funzione ReadFileEx o WriteFileEx perché queste funzioni dispongono di meccanismi di I/O asincroni personalizzati.
È consigliabile non condividere un handle di file associato a una porta di completamento di I/O usando l'ereditarietà dell'handle o una chiamata alla funzione DuplicateHandle . Le operazioni eseguite con tali handle duplicati generano notifiche di completamento. È consigliabile prestare attenzione.
L'handle di porta di completamento di I/O e ogni handle di file associato a quella determinata porta di completamento I/O sono noti come riferimenti alla porta di completamento di I/O. La porta di completamento di I/O viene rilasciata quando non sono presenti altri riferimenti. Pertanto, tutti questi handle devono essere chiusi correttamente per rilasciare la porta di completamento di I/O e le relative risorse di sistema associate. Dopo aver soddisfatto queste condizioni, chiudere l'handle della porta di completamento I/O chiamando la funzione CloseHandle .
In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.
| Tecnologia | Supportato |
|---|---|
| Protocollo SMB (Server Message Block) 3.0 |
Sì |
| Failover trasparente SMB 3.0 (TFO) |
Sì |
| SMB 3.0 con condivisioni file di scalabilità orizzontale (SO) |
Sì |
| File system del volume condiviso cluster (CsvFS) |
Sì |
| Resilient File System (ReFS) |
Sì |
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato |
Windows XP [app desktop | App UWP] |
| Server minimo supportato |
Windows Server 2003 [app desktop | App UWP] |
| Intestazione |
|
| Libreria |
|
| DLL |
|