EPOLL(7)

NOM
epoll - Notifications d'événements d'entrées-sorties

SYNOPSIS
#include <sys/epoll.h>

DESCRIPTION
epoll est une variante de poll(2) que l'on peut déclencher par niveau ou par changement d'état, et monte bien en charge pour un grand nombre de descripteurs simultanés. Trois appels système sont fournis pour configurer et commander un ensemble epoll : epoll_create(2), epoll_ctl(2), epoll_wait(2). Un ensemble epoll est connecté à un descripteur de fichier créé par epoll_create(2). L'interêt pour certains descripteurs est ensuite enregistré avec epoll_ctl(2). Enfin, l'attente effective démarre avec l'appel epoll_wait(2).

  Sétection de niveau et détection de changement d'état
L'interface de distribution d'événements de epoll est capable de se comporter en détection de niveau (Level Triggered - LT) ou en détection de changement d'état (Edge Triggered - ET). La différence entre ces deux mécanismes est décrite ci-dessous. Supposons que le scénario suivant se produise :

1.  Le descripteur de fichier qui représente le côté lecture d'un tube (fd_lect) est ajouté dans un ensemble epoll.

2.  Celui qui écrit dans le tube envoie 2 Ko de données.

3.  Un appel à epoll_wait(2) est effectué et renvoie fd_lect comme descripteur de fichier prêt.

4   Le lecteur du tube lit 1 Ko de données depuis fd_lect.

5.  Un appel de epoll_wait(2) est effectué.

Si le descripteur fd_lect a été ajouté à l'ensemble epoll en utilisant l'attribut EPOLLET (edge-triggered), l'appel epoll_wait(2), réalisé à l'étape 5, va probablement bloquer à cause des données toujours présentes dans les tampons d'entrée du fichier et le pair distant attendra une réponse basée sur les données qu'il a déjà envoyé. La raison en est que le mécanisme de distribution d'événements Edge Triggered délivre les événements seulement lorsque des événements surviennent sur le périphérique supervisé. Ainsi, à l'étape 5, l'appelant devrait cesser d'attendre des données qui sont déjà présentes dans le tampon d'entrée. Dans l'exemple ci-dessus, un événement sur fd_lect sera déclenché à cause de l'écriture à l'étape 2, et l'événement est consommé dans 3. Comme l'opération de lecture de l'étape 4 ne consomme pas toutes les données du tampon, l'appel à epoll_wait(2) effectué à l'étape 5 peut bloquer indéfiniment. Une application qui utilise l'attribut EPOLLET devrait toujours utiliser des descripteurs non bloquants pour éviter qu'une lecture ou une écriture bloque une tâche qui gère plusieurs descripteurs de fichier. L'utilisation suggérée d'epoll avec l'interface en détection de changements (EPOLLET) est décrite ci-dessous :

    i   avec des descripteurs non bloquants ;

    ii  en attendant seulement après qu'un read(2) ou un write(2) ait renvoyé EAGAIN.

Au contraire, lorsqu'il est utilisé avec l'interface en détection de niveau (ce qui est la valeur par défaut lorsque EPOLLET n'est pas spécifié), epoll est une alternative plus rapide à poll(2), et peut être employé chaque fois que poll() est utilisé, car il utilise la même sémantique. Même dans un epoll de type Edge Triggered, plusieurs événements peuvent être générés à la réception de nombreux blocs de données. L'appelant peut, en spécifiant l'attribut EPOLLONESHOT, faire déactiver par epoll le descripteur de fichier associé, après la réception d'un événement avec epoll_wait(2). Lorsque l'attribut EPOLLONESHOT est spécifié, il est de la responsabilité de l'appelant de réarmer le descripteur en utilisant epoll_ctl(2) avec EPOLL_CTL_MOD.

  Exemple d'utilisation conseillée
Tandis que l'utilisation de epoll avec un déclenchement par niveau correspond à la même sémantique que poll(2), le déclenchement par changement d'état nécessite plus d'explication pour éviter les cas de blocage. Dans cet exemple, le lecteur emploie une socket non bloquante sur laquelle listen(2) a été appelée. La fonction do_use_fd() va utiliser le nouveau descripteur de fichier, jusqu'à ce que EAGAIN soit renvoyé par read(2) ou par write(2). Une application fonctionnant par transition d'état devrait, après réception de EAGAIN, enregistrer l'état en cours, afin que l'appel suivant de do_use_fd() continue avec le read(2) ou le write(2) où il s'est arrêté.
struct epoll_event ev, *events;
for (;;) {
    nfds = epoll_wait(kdpfd, events, maxevents, -1);
    for (n = 0; n < nfds; ++n) {
        if (events[n].data.fd == listener) {
            client = accept(listener, (struct sockaddr *) &local,
                            &addrlen);
            if (client < 0) {
                perror("accept");
                continue;
            }
            setnonblocking(client);
            ev.events = EPOLLIN | EPOLLET;
            ev.data.fd = client;
            if (epoll_ctl(kdpfd, EPOLL_CTL_ADD, client, &ev) == -1) {
                fprintf(stderr, "epoll set insertion error: fd=%d\n",
                        client);
                return -1;
            }
        } else {
            do_use_fd(events[n].data.fd);
        }
    }
}
Lorsqu'on utilise une détection de changement d'états, pour des raisons de performances, il est possible d'ajouter le descripteur de fichier dans l'interface epoll (EPOLL_CTL_ADD) une fois, en spécifiant (EPOLLIN|EPOLLOUT). Ceci évite de basculer sans cesse entre EPOLLIN et EPOLLOUT lors des appels epoll_ctl(2) avec EPOLL_CTL_MOD.

  Questions et réponses

Q0  Quelle est la clé utilisée pour distinguer les descripteurs de fichier dans un ensemble epoll ?

A0  La clé est la combinaison du numéro de descripteur de fichier et de la description de fichier ouvert (également connu comme « identificateur de fichier ouvert », la représentation interne du noyau d'un fichier ouvert).

Q1  Que se passe-t-il si on ajoute deux fois le même descripteur de fichier dans un ensemble epoll ?

A1  On aura probablement l'erreur EEXIST. Toutefois, il est possible d'ajouter un descripteur de fichier dupliqué (dup(2), dup2(2), fcntl(2) F_DUPFD) au même ensemble epoll. Cela peut être une technique pour le filtrage d'événements si les descripteurs de fichier dupliqués sont enregistrés avec différents masques events.

Q2  Deux ensembles epoll peuvent-ils attendre le même fd ? Si oui, les événements seront-ils reportés sur les deux ensembles epoll en même temps ?

A2  Oui, l'événement sera rapporté pour les deux. Toutefois, une programmation soignée est nécessaire pour que cela soit fait correctement.

Q3  Peut-on utiliser le descripteur epoll lui-même avec poll/epoll/select ?

A3  Oui. Si un descripteur de fichier epoll a des événements en attente, il indiquera qu'il est accessible en lecture.

Q4  Que se passe-t-il si le descripteur de epoll est inséré dans son propre ensemble ?

A4  L'appel epoll_ctl(2) échouera. (EINVAL). Toutefois vous pouvez ajouter le descripteur de epoll dans un autre ensemble epoll.

Q5  Puis-je envoyer un descripteur epoll à travers une socket de domaine Unix vers un autre processus ?

A5  Oui, mais cela n'a aucun sens de faire cela puisque le processus récepteur n'aura pas de copies des descripteurs de fichier dans l'ensemble epoll.

Q6  Est-ce que la fermeture d'un descripteur le supprime automatiquement d'un ensemble epoll ?

A6  Oui, mais faites attention au point suivant. Un descripteur de fichier est une référence vers une description de fichier ouvert (voir open(2)). Chaque fois qu'un descripteur est dupliqué avec dup(2), dup2(2), l'attribut F_DUPFD de fcntl(2), ou fork(2), un nouveau descripteur de fichier faisant référence à la même description de fichiers est créé. Une description de fichier ouvert continue à exister jusqu'à ce que tous les descripteurs de fichier lui faisant référence aient été fermés. Un descripteur de fichier est supprimé d'un ensemble epoll seulement après que tous les descripteurs de fichier faisant référence à la description de fichier ouvert sous-jacente aient été fermés (ou avant si le descripteur est explicitement supprimé avec l'attribut EPOLL_CTL_DEL de epoll_ctl()). Cela signifie que même après qu'un descripteur de fichier, qui appartient à un ensemble epoll, ait été fermé, les événements peuvent être rapportés pour ce descripteur de fichier si d'autres descripteurs de fichier faisant référence à la même description de fichier sous-jacente restent ouverts.

Q7  Si plus d'un événement survient entre deux appels epoll_wait(2), sont-ils combinés ou rapportés séparément ?

A7  Ils sont combinés..

Q8  Est-ce qu'une opération sur un descripteur affecte les événements déjà collectés mais pas encore rapportés ?

A8  Vous pouvez faire deux choses sur un descripteur existant. Une suppression serait sans signification dans ce cas. Une modification re-vérifie les entrées-sorties disponibles.

Q9  Dois-je lire/écrire sans cesse un descripteur jusqu'à obtenir EAGAIN avec l'attribut EPOLLET (Edge Triggered behaviour) ?

A9  La réception d'un événement depuis epoll_wait(2) suggère qu'un descripteur est prêt pour l'opération d'E/S désirée. Vous devez le considérer prêt jusqu'à ce que la prochaine lecture/écriture produise une erreur EAGAIN.

    Pour les fichiers orientés paquet/jeton (par exemple socket de datagramme, terminal en mode canonique), la seule façon de détecter la fin de l'espace d'E/S de lecture/écriture est de continuer à lire/écrire jusqu'à l'apparition de l'erreur EAGAIN. Quand et comment utiliser le descripteur dépend de vous.

    Pour les fichiers orientés flux (par exemple, tube, FIFO, socket flux), la disponibilité des entrées-sorties peut-être vérifiée par la quantité de données lues ou écrites avec le descripteur. Par exemple, si vous appelez read(2) en demandant la lecture d'une certaine quantité de données et que read(2) en renvoie moins, vous pouvez être sûrs d'avoir consommé tout le tampon d'entrée pour le descripteur de fichier. La même chose est vraie pour l'appel système write(2). (Évitez cette dernière technique si vous ne pouvez pas garantir que le descripteur de fichier surveillé fasse toujours référence à un fichier orienté flux.)

  Pièges possibles et solutions

o Faux Positifs (Edge Triggered)

Il est possible que durant une lecture (en supposant que vous lisez en boucle en attendant EAGAIN), des données supplémentaires arrivent en second événement. Bien que ces données soient lues tout de suite, l'appel suivant de epoll_wait(2) sur le descripteur dira qu'il y a un événement « lecture possible » alors qu'il a déjà été consommé.

1   Une certaine quantité de données arrive sur un descripteur surveillé.

2   Un appel à epoll_wait(2) renvoie le descripteur repéré.

3   Un autre bloc de données arrive sur la même descripteur.

4   Le descripteur est signalé en interne comme prêt.

5   Un appel à read(2) consomme toutes les données disponibles.

6   Un autre appel à epoll_wait(2) renverra le descripteur ci-dessus même si aucune donnée n'est disponible, ainsi l'appel suivant de read(2) renverra EAGAIN.

Dans le cas de descripteurs non bloquants, cela fera échouer immédiatement la lecture suivante avec l'erreur EAGAIN. Dans le cas de descripteurs bloquants, on restera en attente pour lire des données non encore présentes. L'auteur recommande de ne pas utiliser de descripteur bloquant avec le mécanisme de détection de changement d'état (ET).

Pour traiter ce cas, une possibilité est de marquer le descripteur comme prêt dans sa structure de données associée après la réception du premier événement, puis d'ignorer les événements tant qu'il est dans l'état prêt. Lorsque vous lisez jusqu'à recevoir EAGAIN, effacez le bit d'état prêt avant de rappeler epoll_wait(2) sur ce descripteur.

o Famine (Edge Triggered)

S'il y a un gros volume d'entrées-sorties, il est possible qu'en essayant de les traiter, d'autres fichiers ne soient pas pris en compte, ce qu'on appelle un cas de famine. Ce n'est pas spécifique à epoll.

La solution est de maintenir une liste de descripteurs prêts et de les marquer comme tels dans leur structure associée, permettant à l'application de savoir quels fichiers traiter, en organisant l'ordre au mieux. Ceci permet aussi d'ignorer les événements ultérieurs sur un descripteur prêt.

o Utilisation d'un cache d'événements...

Si vous utilisez un cache d'événement, ou stockez tous les descripteurs renvoyés par epoll_wait(2), alors assurez vous de disposer d'un moyen de marquer dynamiquement leurs fermetures (causées par un événement précédent). Supposons que vous recevez 100 événements de epoll_wait(2), et que l'événement 47 implique de fermer le descripteur 13. Si vous supprimez la structure et utilisez close(2), alors votre cache peut encore contenir des événements pour ce descripteur, et poser des problèmes de cohérence.

Une solution est d'invoquer, pendant le traitement de l'événement 47, epoll_ctl(EPOLL_CTL_DEL) pour supprimer le descripteur 13, le fermer, et marquer sa structure associée comme supprimée. Si vous rencontrez un autre événement pour le descripteur 13 dans votre traitement, vous verrez qu'il a été supprimé précédemment, sans que cela ne prête à confusion.

VERSIONS
L'API epoll a été introduite dans Linux 2.5.44. Son interface devrait être finalisée depuis le 2.5.66.

CONFORMITÉ
L'API epoll est spécifique à Linux. Certains autres systèmes fournissent des mécanismes similaires, par exemple, FreeBSD a kqueue, et Solaris a /dev/poll.

VOIR AUSSI
epoll_create(2), epoll_ctl(2), epoll_wait(2)

TRADUCTION

Ce document est une traduction réalisée par Christophe Blaess <ccb AT club-internet DOT fr> le 25 juillet 2003, mise à jour par Alain Portal <aportal AT univ-montp2 DOT fr> le 23 décembre 2005 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 4 epoll ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.