LPFN_RIOCREATECOMPLETIONQUEUE fonction de rappel (mswsock.h)

Article
03/04/2024

La fonction RIOCreateCompletionQueue crée une file d’attente d’achèvement d’E/S d’une taille spécifique à utiliser avec les extensions d’E/S inscrites dans Winsock.

Syntaxe

LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;

RIO_CQ LpfnRiocreatecompletionqueue(
  DWORD QueueSize,
  PRIO_NOTIFICATION_COMPLETION NotificationCompletion
)
{...}

Paramètres

QueueSize

Taille, en nombre d’entrées, de la file d’attente d’achèvement à créer.

NotificationCompletion

Type d’achèvement de notification à utiliser en fonction du membre Type de la structure RIO_NOTIFICATION_COMPLETION (achèvement des E/S ou notification d’événement).

Si le membre Type est défini sur RIO_EVENT_COMPLETION, le membre Event de la structure RIO_NOTIFICATION_COMPLETION doit être défini.

Si le membre Type est défini sur RIO_IOCP_COMPLETION, le membre Iocp de la structure RIO_NOTIFICATION_COMPLETION doit être défini et le membre Iocp.Overlapped de la structure RIO_NOTIFICATION_COMPLETION ne doit pas être NULL.

Si le paramètre NotificationCompletion a la valeur NULL, cela spécifie qu’aucune saisie semi-automatique de notification n’est utilisée et que l’interrogation doit être utilisée pour déterminer l’achèvement.

Valeur retournée

Si aucune erreur ne se produit, la fonction RIOCreateCompletionQueue retourne un descripteur référençant une nouvelle file d’attente d’achèvement. Sinon, une valeur de RIO_INVALID_CQ est retournée et un code d’erreur spécifique peut être récupéré en appelant la fonction WSAGetLastError .

Code de retour	Description
WSAEFAULT	Le système a détecté une adresse de pointeur non valide lors de la tentative d’utilisation d’un argument pointeur dans un appel.
WSAEINVAL	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si le paramètre QueueSize est inférieur à 1 ou supérieur à RIO_MAX_CQ_SIZE défini dans le fichier d’en-tête Mswsockdef.h .
WSAENOBUFS	La mémoire insuffisante n’a pas pu être allouée. Cette erreur est retournée si la mémoire était insuffisante pour allouer la file d’attente d’achèvement demandée en fonction du paramètre QueueSize .

Remarques

La fonction RIOCreateCompletionQueue crée une file d’attente d’achèvement des E/S d’une taille spécifique. La taille de la file d’attente d’achèvement limite l’ensemble des sockets d’E/S inscrits qui peuvent être associés à la file d’attente d’achèvement. Pour plus d’informations, consultez la fonction RIOCreateRequestQueue .

Lors de la création d’un RIO_CQ, la structure RIO_NOTIFICATION_COMPLETION pointée par le paramètre NotificationCompletion détermine la façon dont l’application recevra les notifications de file d’attente d’achèvement. Si une structure RIO_NOTIFICATION_COMPLETION est fournie lors de la création de la file d’attente d’achèvement, l’application peut appeler la fonction RIONotify pour demander une notification de file d’attente d’achèvement. Normalement, cette notification se produit lorsque la file d’attente d’achèvement n’est pas vide. Cela peut se produire immédiatement ou lorsque l’entrée de saisie semi-automatique suivante est insérée dans la file d’attente d’achèvement. Toutefois, les demandes d’envoi et de réception peuvent être marquées comme RIO_MSG_DONT_NOTIFY. Notification de file d’attente d’achèvement et ne sera jamais déclenchée à la suite de ces demandes. Si la file d’attente d’achèvement contient uniquement des entrées avec l’indicateur RIO_MSG_DONT_NOTIFY défini, la notification de file d’attente d’achèvement ne sera pas déclenchée. En outre, lorsqu’une nouvelle entrée entre dans la file d’attente d’achèvement, la notification de file d’attente d’achèvement est déclenchée uniquement si l’indicateur RIO_MSG_DONT_NOTIFY n’a pas été défini sur la demande associée. Toutes les demandes terminées peuvent toujours être récupérées par interrogation à l’aide de la fonction RIODequeueCompletion . Une fois qu’une notification de file d’attente d’achèvement est émise, l’application doit appeler la fonction RIONotify pour recevoir une autre notification de file d’attente d’achèvement. Lorsqu’une notification de file d’attente d’achèvement se produit, l’application appelle généralement la fonction RIODequeueCompletion pour mettre en file d’attente les demandes d’envoi ou de réception terminées.

Deux options sont disponibles pour la notification de file d’attente d’achèvement.

Handles d’événements.
Ports d’achèvement des E/S

Si le membre Type de la structure RIO_NOTIFICATION_COMPLETION est défini sur RIO_EVENT_COMPLETION, un handle d’événement est utilisé pour signaler les notifications de file d’attente d’achèvement. Un handle d’événement est fourni en tant que membre EventNotify.EventHandle dans la structure RIO_NOTIFICATION_COMPLETION passée à la fonction RIOCreateCompletionQueue . Le membre Event.EventHandle doit contenir le handle d’un événement créé par la fonction WSACreateEvent ou CreateEvent . Pour recevoir l’achèvement RIONotify , l’application doit attendre le handle d’événement spécifié à l’aide de WSAWaitForMultipleEvents ou d’une routine d’attente similaire. L’achèvement de la fonction RIONotify pour cette RIO_CQ signale l’événement. Le membre Event.NotifyReset dans la structure RIO_NOTIFICATION_COMPLETION passée à la fonction RIOCreateCompletionQueue indique si l’événement doit être réinitialisé ou non dans le cadre d’un appel à la fonction RIONotify . Si l’application prévoit de réinitialiser et de réutiliser l’événement, l’application peut réduire la surcharge en définissant le membre Event.NotifyReset sur une valeur différente de zéro. Cela entraîne la réinitialisation automatique de l’événement par la fonction RIONotify lorsque la notification se produit. Cela atténue la nécessité d’appeler la fonction WSAResetEvent pour réinitialiser l’événement entre les appels à la fonction RIONotify .

Si le membre Type de la structure RIO_NOTIFICATION_COMPLETION est défini sur RIO_IOCP_COMPLETION, un port d’achèvement d’E/S est utilisé pour signaler les notifications de file d’attente d’achèvement. Un handle de port d’achèvement d’E/S est fourni en tant que membre Iocp.IocpHandle dans la structure RIO_NOTIFICATION_COMPLETION passée à la fonction RIOCreateCompletionQueue . L’achèvement de la fonction RIONotify pour cette RIO_CQ met en file d’attente une entrée vers le port d’achèvement des E/S qui peut être récupérée à l’aide de la fonction GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . Une entrée mise en file d’attente a la valeur du paramètre lpCompletionKey retournée définie sur la valeur spécifiée dans le membre Iocp.CompletionKey de la structure RIO_NOTIFICATION_COMPLETION et le membre Iocp.Overlapped dans la structure RIO_NOTIFICATION_COMPLETION sera une valeur non NULL.

En termes d’utilisation, la notification de file d’attente d’achèvement est conçue pour réveiller un thread d’application en attente afin que le thread puisse examiner la file d’attente d’achèvement. L’éveil et la planification d’un thread ont un coût. Si cela se produit trop fréquemment, cela aura un impact négatif sur les performances de l’application. L’indicateur RIO_MSG_DONT_NOTIFY est fourni afin que l’application puisse contrôler la fréquence de ces événements et limiter leur impact sur les performances.

Notes

Par souci d’efficacité, l’accès aux files d’attente d’achèvement (RIO_CQ structs) et aux files d’attente de requêtes (RIO_RQ structs) ne sont pas protégés par des primitives de synchronisation. Si vous devez accéder à une file d’attente d’achèvement ou de demandes à partir de plusieurs threads, l’accès doit être coordonné par une section critique, un verrou d’écriture de lecteur mince ou un mécanisme similaire. Ce verrouillage n’est pas nécessaire pour l’accès par un seul thread. Différents threads peuvent accéder à des files d’attente de requêtes/d’achèvement distinctes sans verrous. La synchronisation est nécessaire uniquement lorsque plusieurs threads tentent d’accéder à la même file d’attente. La synchronisation est également nécessaire si plusieurs problèmes de threads envoient et reçoivent sur le même socket, car les opérations d’envoi et de réception utilisent la file d’attente de demandes du socket.

Notes

Le pointeur de fonction vers la fonction RIOCreateCompletionQueue doit être obtenu au moment de l’exécution en effectuant un appel à la fonction WSAIoctl avec l’opcode SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER spécifié. La mémoire tampon d’entrée passée à la fonction WSAIoctl doit contenir WSAID_MULTIPLE_RIO, un identificateur global unique (GUID) dont la valeur identifie les fonctions d’extension d’E/S inscrites dans Winsock. En cas de réussite, la sortie retournée par la fonction WSAIoctl contient un pointeur vers la structure RIO_EXTENSION_FUNCTION_TABLE qui contient des pointeurs vers les fonctions d’extension d’E/S inscrites dans Winsock. Le SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL est défini dans le fichier d’en-tête Ws2def.h . Le GUID WSAID_MULTIPLE_RIO est défini dans le fichier d’en-tête Mswsock.h .

Windows Phone 8 : cette fonction est prise en charge pour les applications Windows Phone Store sur Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Configuration requise

Condition requise	Valeur
En-tête	mswsock.h

Partager via