LPFN_RIOCREATECOMPLETIONQUEUE funzione di callback (mswsock.h)
La funzione RIOCreateCompletionQueue crea una coda di completamento di I/O di dimensioni specifiche da usare con le estensioni di I/O registrate winsock.
Sintassi
LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;
RIO_CQ LpfnRiocreatecompletionqueue(
DWORD QueueSize,
PRIO_NOTIFICATION_COMPLETION NotificationCompletion
)
{...}
Parametri
QueueSize
Dimensioni, in numero di voci, della coda di completamento da creare.
NotificationCompletion
Tipo di completamento della notifica da usare in base al membro Type della struttura RIO_NOTIFICATION_COMPLETION (completamento di I/O o notifica dell'evento).
Se il membro Type è impostato su RIO_EVENT_COMPLETION, è necessario impostare il membro Evento della struttura RIO_NOTIFICATION_COMPLETION .
Se il membro Type è impostato su RIO_IOCP_COMPLETION, il membro Iocpdella struttura RIO_NOTIFICATION_COMPLETION deve essere impostato e il membro Iocp.Overlapped della struttura RIO_NOTIFICATION_COMPLETION non deve essere NULL.
Se il parametro NotificationCompletion è NULL, questo specifica che non viene usato alcun completamento della notifica e che il polling deve essere usato per determinare il completamento.
Valore restituito
Se non si verifica alcun errore, la funzione RIOCreateCompletionQueue restituisce un descrittore che fa riferimento a una nuova coda di completamento. In caso contrario, viene restituito un valore di RIO_INVALID_CQ e un codice di errore specifico può essere recuperato chiamando la funzione WSAGetLastError .
| Codice restituito | Descrizione |
|---|---|
| Il sistema ha rilevato un indirizzo puntatore non valido nel tentativo di usare un argomento puntatore in una chiamata. |
|
| Un parametro non valido è stato passato alla funzione. Questo errore viene restituito se il parametro QueueSize è minore di 1 o maggiore di RIO_MAX_CQ_SIZE definito nel file di intestazione Mswsockdef.h . |
|
| Impossibile allocare memoria sufficiente. Questo errore viene restituito se è presente memoria insufficiente per allocare la coda di completamento richiesta in base al parametro QueueSize . |
Commenti
La funzione RIOCreateCompletionQueue crea una coda di completamento di I/O di dimensioni specifiche. Le dimensioni della coda di completamento limitano il set di socket di I/O registrati che possono essere associati alla coda di completamento. Per altre informazioni, vedere la funzione RIOCreateRequestQueue .
Quando si crea un RIO_CQ, la struttura RIO_NOTIFICATION_COMPLETION puntata dal parametro NotificationCompletion determina come l'applicazione riceverà le notifiche della coda di completamento. Se viene fornita una struttura RIO_NOTIFICATION_COMPLETION durante la creazione della coda di completamento, l'applicazione può chiamare la funzione RIONotify per richiedere una notifica della coda di completamento. In genere questa notifica si verifica quando la coda di completamento non è vuota. Ciò può verificarsi immediatamente o quando la voce di completamento successiva viene inserita nella coda di completamento. Tuttavia, le richieste di invio e ricezione possono essere contrassegnate come RIO_MSG_DONT_NOTIFY. Notifica della coda di completamento e non verrà mai attivata come risultato di tali richieste. Se la coda di completamento contiene solo voci con il flag RIO_MSG_DONT_NOTIFY impostato, la notifica della coda di completamento non verrà attivata. Inoltre, quando una nuova voce entra nella coda di completamento, la notifica della coda di completamento viene attivata solo se il flag di RIO_MSG_DONT_NOTIFY non è stato impostato sulla richiesta associata. Tutte le richieste completate possono comunque essere recuperate tramite il polling usando la funzione RIODequeueCompletion . Una volta eseguita una notifica della coda di completamento, l'applicazione deve chiamare la funzione RIONotify per ricevere un'altra notifica della coda di completamento. Quando si verifica una notifica della coda di completamento, l'applicazione chiama in genere la funzione RIODequeueCompletion per dequeue le richieste di invio o ricezione completate.
Per la notifica della coda di completamento sono disponibili due opzioni.
- Handle eventi.
- Porte di completamento di I/O
Se il membro Type della struttura RIO_NOTIFICATION_COMPLETION è impostato su RIO_EVENT_COMPLETION, viene usato un handle eventi per segnalare le notifiche della coda di completamento. Viene fornito un handle di eventi come membro EventNotify.EventHandle nella struttura RIO_NOTIFICATION_COMPLETION passata alla funzione RIOCreateCompletionQueue . Il membro Event.EventHandle deve contenere l'handle per un evento creato dalla funzione WSACreateEvent o CreateEvent . Per ricevere il completamento di RIONotify , l'applicazione deve attendere l'handle di eventi specificato usando WSAWaitForMultipleEvents o una routine di attesa simile. Il completamento della funzione RIONotify per questa RIO_CQ segnalerà l'evento. Il membro Event.NotifyReset nella struttura RIO_NOTIFICATION_COMPLETION passato alla funzione RIOCreateCompletionQueue indica se l'evento deve essere reimpostato come parte di una chiamata alla funzione RIONotify . Se l'applicazione prevede di reimpostare e riutilizzare l'evento, l'applicazione può ridurre il sovraccarico impostando il membro Event.NotifyReset su un valore diverso da zero. Ciò causa la reimpostazione automatica dell'evento dalla funzione RIONotify quando si verifica la notifica. Ciò riduce la necessità di chiamare la funzione WSAResetEvent per reimpostare l'evento tra le chiamate alla funzione RIONotify .
Se il membro Type della struttura RIO_NOTIFICATION_COMPLETION è impostato su RIO_IOCP_COMPLETION, viene usata una porta di completamento di I/O per segnalare le notifiche della coda di completamento. Viene fornito un handle di porta di completamento I/O come membro Iocp.IocpHandle nella struttura RIO_NOTIFICATION_COMPLETION passata alla funzione RIOCreateCompletionQueue . Il completamento della funzione RIONotify per questa RIO_CQ accoderà una voce alla porta di completamento di I/O che può essere recuperata usando la funzione GetQueuedCompletionStatus o GetQueuedCompletionStatusEx. Una voce in coda avrà il valore del parametro lpCompletionKey restituito impostato sul valore specificato nel membro Iocp.CompletionKey della struttura RIO_NOTIFICATION_COMPLETION e il membro Iocp.Overlapped nella struttura RIO_NOTIFICATION_COMPLETION sarà un valore non NULL.
In termini di utilizzo, la notifica della coda di completamento è progettata per riattivare un thread di applicazione in attesa in modo che il thread possa esaminare la coda di completamento. La riattivazione e la pianificazione di un thread comporta un costo, quindi, se ciò accade troppo spesso, avrà un impatto negativo sulle prestazioni dell'applicazione. Il flag RIO_MSG_DONT_NOTIFY viene fornito in modo che l'applicazione possa controllare la frequenza di questi eventi e limitare l'impatto sulle prestazioni.
Nota
Ai fini dell'efficienza, l'accesso alle code di completamento (RIO_CQ struct) e alle code delle richieste (RIO_RQ struct) non sono protette dalle primitive di sincronizzazione. Se è necessario accedere a una coda di completamento o richiesta da più thread, l'accesso deve essere coordinato da una sezione critica, un blocco di scrittura di lettura sottile o un meccanismo simile. Questo blocco non è necessario per l'accesso da un singolo thread. I diversi thread possono accedere a code separate di richieste/completamento senza blocchi. La necessità di sincronizzazione si verifica solo quando più thread tentano di accedere alla stessa coda. La sincronizzazione è necessaria anche se vengono inviati e ricevuti più thread nello stesso socket perché le operazioni di invio e ricezione usano la coda di richieste del socket.
Nota
Il puntatore alla funzione RIOCreateCompletionQueue deve essere ottenuto in fase di esecuzione eseguendo una chiamata alla funzione WSAIoctl con il codice opcode SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER specificato. Il buffer di input passato alla funzione WSAIoctl deve contenere WSAID_MULTIPLE_RIO, un identificatore univoco globale (GUID) il cui valore identifica le funzioni di estensione I/O registrate Winsock. In caso di esito positivo, l'output restituito dalla funzione WSAIoctl contiene un puntatore alla struttura RIO_EXTENSION_FUNCTION_TABLE che contiene puntatori alle funzioni di estensione di I/O registrate Winsock. Il SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL è definito nel file di intestazione Ws2def.h . Il GUID WSAID_MULTIPLE_RIO è definito nel file di intestazione Mswsock.h .
Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.
Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.
Requisiti
| Requisito | Valore |
|---|---|
| Intestazione | mswsock.h |