File: epoll.4

package info (click to toggle)
manpages-fr 1.58.1-3
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 10,104 kB
  • ctags: 4
  • sloc: makefile: 106; sh: 8
file content (410 lines) | stat: -rw-r--r-- 11,677 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
.\"
.\"  epoll by Davide Libenzi ( efficient event notification retrieval )
.\"  Copyright (C) 2003  Davide Libenzi
.\"
.\"  This program is free software; you can redistribute it and/or modify
.\"  it under the terms of the GNU General Public License as published by
.\"  the Free Software Foundation; either version 2 of the License, or
.\"  (at your option) any later version.
.\"
.\"  This program is distributed in the hope that it will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"
.\"  You should have received a copy of the GNU General Public License
.\"  along with this program; if not, write to the Free Software
.\"
.\"  Davide Libenzi <davidel@xmailserver.org>
.\"  Traduction Christophe Blaess, <ccb@club-internet.fr>
.\" MJ 25/07/2003 LDP-1.57
.TH EPOLL 4 "25 juillet 2003" LDP "Manuel du programmeur Linux"
.SH NOM
epoll \- Notifications d'vnements d'entres/sorties.
.SH SYNOPSIS
.B #include <sys/epoll.h>
.SH DESCRIPTION
.B epoll
est une variante de
.BR poll (2)
que l'on peut dclencher par niveau ou par changement d'tat, et monte
bien en charge pour un grand nombre de descripteurs simultans. Trois appels-systme
sont fournis pour configurer et commander un ensemble
.BR epoll " :"
.BR epoll_create (2),
.BR epoll_ctl (2),
.BR epoll_wait (2).

Un ensemble
.B epoll
est connect  un descripteur de fichiers cr par
.BR epoll_create (2).
L'intert pour certains descripteurs est ensuite enregistr avec
.BR epoll_ctl (2).
Enfin, l'attente effective dmarre avec l'appel 
.BR epoll_wait (2).

.SH NOTES
L'interface de distribution d'vnement de
.B epoll
est capable de se comporter en dtection de niveau (Level Triggered - LT)
ou en dtection de changement d'tat (Edge Triggered - ET). La diffrence
entre ces mcanismes est dcrite ci-dessous. Supposons que le
scnario suivant se produise\ :
.TP
.B 1
Le descripteur de fichier qui reprsente le ct lecture d'un tube
.RB ( fd_lect )
est ajout dans un ensemble
.BR epoll .
.TP
.B 2
Celui qui crit dans le tube envoie 2 Ko de donnes.
.TP
.B 3
Un appel 
.BR epoll_wait (2)
est effectu et renvoie
.B fd_lect
comme descripteur de fichier prt.
.TP
.B 4
Le lecture du tube lit 1 Ko de donnes depuis
.BR fd_lect .
.TP
.B 5
Un appel de
.BR epoll_wait (2)
est effectu.
.PP

Si le descripteur
.B fd_lect
a t ajout  l'ensemble
.B epoll
en utilisant l'attribut
.BR EPOLLET ,
l'appel
.BR epoll_wait (2)
ralis  l'tape
.B 5
va bloquer malgr les donnes dj prsentes dans les buffers d'entre
du fichier. La raison en est que le mcanisme ET dtecte les changements
sur un priphrique supervis entre l'tat "aucune entre/sortie possible"
.RB ( 0 )
et l'tat "entre/sortie possible"
.RB ( 1 ).
Dans l'exemple ci-dessus, un vnement sur
.B fd_lect
sera dclench (en supposant que le buffer tait vide  l'origine)
 cause de l'criture  l'tape
.BR 2 ,
et l'vnement est consomm dans
.BR 3 .
Comme l'opration de lecture de l'tape
.B 4
ne consomme pas toutes les donnes du buffer (la condition "Entres/sorties
possibles" persiste), aucune transition
.B 0
->
.B 1
ne peut se produire en
.BR 5 .
Lorsqu'on emploie l'attribut
.B EPOLLET
(Edge Triggered)
de la fonction
.BR epoll ,
on devrait toujours utiliser des descripteurs non-bloquants pour viter 
qu'une lecture ou une criture bloque une tche qui gre plusieurs
descripteurs de fichiers.
L'utilisation suggre d
.B epoll
avec l'interface en dtection de changements
.RB ( EPOLLET )
est dcrite ci-dessous, avec les piges  viter.
.SR
.TP 
.B i
ave des descripteurs non-bloquants\ ;
.TP 
.B ii
en attendant seulement aprs qu'un
.BR read (2)
ou un
.BR write (2)
ait renvoy EAGAIN.
.SE
.PP
Au contraire, lorsqu'il est utilis avec l'interface en dtection de niveau
.B epoll
est une alternative plus rapide 
.BR poll (2),
et peut tre employ chaque fois que poll() est utilis, car il utilise
la mme smantique.

.SH "EXEMPLE D'UTILISATION CONSEILLE"

Tandis que l'utilisation de
.B epoll
avec un dclenchement par niveau correspond  la mme smantique
que
.BR poll (2),
le dclenchement par changement d'tat ncessite plus d'explication pour
viter les cas de blocage. Dans cet exemple, le lecteur emploie
une socket non-bloquante sur laquelle
.BR listen (2)
a t appele. La fonction do_use_fd() va utiliser le nouveau descripteur
de fichier, jusqu' ce que EAGAIN soit renvoy par
.BR read (2)
ou par
.BR write (2).
Une application fonctionnant par transition d'tat devrait, aprs rception
d'EAGAIN, enregistrer l'tat en cours, afin que l'appel suivant de
do_use_fd() continue avec le
.BR read (2)
ou le 
.BR write (2)
o il s'est arrt.  

.nf
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) < 0) {
                fprintf(stderr, "epoll set insertion error: fd=%d\n",
                        client);
                return -1;
            }
        }
        else
            do_use_fd(events[n].data.fd);
    }
}
.fi

Lorsqu'on utilise une dtection de changement d'tats, pour des raisons de
performances, il est possible d'ajouter le descriptuer de fichier dans
l'interface epoll
.RB ( EPOLL_CTL_ADD )
une fois, en spcifiant
.RB ( EPOLLIN | EPOLLOUT ).
Ceci vite de basculer sans
cesse entre
.B EPOLLIN
et
.B EPOLLOUT
lors des appels
.BR epoll_ctl (2)
avec
.BR EPOLL_CTL_MOD .

.SH "QUESTIONS ET REPONSES (de la liste linux-kernel)"

.SR
.TP 
.B Q1 
Que se passe-t-il si on ajoute deux fois le mme fd dans un ensemble epoll\ ?
.TP
.B A1 
On aura probablement l'erreur EEXIST. Toutefois, il est possible que deux
threads puisse ajouter le mme fd deux fois. Sans consquences fcheuses.
.TP
.B Q2 
Deux ensemples
.B epoll
peuvent-ils attendre le mme fd? Si oui, les vnements seront-t-ils
reports sur des deux ensembles
.B epoll
en mme temps\ ?
.TP
.B A2
Oui. Toutefois, c'est peu recommand. Oui, l'vnement sera rapport pour
les deux.
.TP
.B Q3
Peut-on utiliser le descripteur
.B epoll
lui-mme avec poll/epoll/select\ ?
.TP
.B A3
Oui.
.TP
.B Q4 
Que se passe-t-il si le descripteur de
.B epoll
est insr dans son propre ensemble\ ?
.TP
.B A4
Cela chouera. Toutefois vous pouvez ajoutez le descripteur de
.B epoll
dans un autre ensemble epoll. 
.TP
.B Q5
Puis-je envoyer le descripteur
.B epoll
 travers une socket Unix vers un autre processus\ ?
.TP
.B A5
Non.
.TP
.B Q6
Est-ce que la feermeteur d'un descripteur le supprime 
automatiquement d'un ensemble
.B epoll " ?"
.TP
.B A6
Oui.
.TP
.B Q7 
Si plus d'un vnement survient entre deux appels
.BR epoll_wait (2),
sont-ils combins ou rapports sparment\ ?
.TP
.B A7
Ils sont combins..
.TP
.B Q8
Est-ce qu'une opration sur un descripteur affecte les vnements dj
collects mais pas encore rapports\ ?
.TP
.B A8
Vous pouvez faire deux choses sur un descripteur existant. Une suppression
serait sans signification dans ce cas. Une modification re-vrifie les
entres/sorties disponibles.
.TP
.B Q9
Dois-je lire/crire sans cesse un descripteur jusqu' obtenir EAGAIN avec
l'attribut
.B EPOLLET
(Edge Triggered behaviour)\ ?
.TP
.B A9
Non. La rception d'un vnement depuis
.BR epoll_wait (2)
suggre qu'un descripteur est prt pour l'opration d'E/S dsire. Vous
devez le considrer prt jusqu'au prochain EAGAIN. Quand et comment
utiliser le descripteur dpend de vous. De plus, la disponibilit des
entres/sorties peut-tre vrifie par la quantit de donnes lues ou
crites avec le descripteur. Par exemple, si vous appelez
.BR read (2)
en demandant la lecture d'une certaine quantit de donnes et que
.BR read (2)
en renvoie moins, vous pouvez tre srs d'avoir consomm tout le buffer
d'entre pour le descripteur. La mme chose est vraie pour
l'appel-systme
.BR write (2).
.SE

.SH "PIGES POSSIBLES, ET SOLUTIONS"
.SR
.TP
.B o Faux Positifs (Edge Triggered)
.PP
Il est possible que durant une lecture (en supposant que vous lisez en
boucle en attendant EAGAIN), des donnes supplmentaires arrivent en
second vnement. Bien que ces donnes soient lues tout de suite, l'appel
suivant de 
.BR epoll_wait (2)
sur le descripteur dira qu'il y a un vnement "lecture possible" alors
qu'il a dj t consomm.
.PP
.TP
.B 1
Une certaine quantit de donnes arrive sur un descripteur surveill.
.TP
.B 2
Un appel 
.BR epoll_wait (2)
renvoit le descripteur repr.
.TP
.B 3
Un autre bloc de donnes arrive sur la mme descripteur.
.TP
.B 4
Le descripteur est signal en interne comme prt.
.TP
.B 5
Un appel 
.BR read (2)
consomme toutes les donnes disponibles.
.TP
.B 6
Un autre appel 
.BR epoll_wait (2)
renverra le descripteur ci-dessus mme si aucune donne
n'est disponible, ainsi l'appel suivant de
.BR read (2)
renverra EAGAIN.
.PP
Dans le cas de descripteurs non-bloquants, cela fera chouer immdiatement
la lecture suivante avec l'erreur EAGAIN. Dans le cas de descripteurs
bloquants, on restera en attente pour lire des donnes non encore prsentes.
L'auteur recommande de ne pas utiliser de descripteur bloquant avec le
mcanisme de dtection de changement d'tat (ET).
.PP 
Pour traiter ce cas, une possibilit est de marquer le descripteur comme
prt dans sa structure de donnes associe aprs la rception du premier
vnement, puis d'ignorer les vnements tant qu'il est dans l'tat prt.
Lorsque vous lisez jusqu' recevoir EAGAIN, effacez le bit d'tat prt
avant de rappeler
.BR epoll_wait (2)
sur ce descripteur.
.TP
.B o Famine (Edge Triggered)
.PP
S'il y a un gros volume d'entres/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 spcifique 
.BR epoll .
.PP
La solution est de maintenir une liste de descripteurs prts et de les
marquer comme tels dans leur structure associe, permettant  l'application
de savoir quels fichiers traiter, en organisant l'ordre au mieux. Ceci
permet aussi d'ignorer les vnments ultrieurs sur un descripteur prt.
.TP
.B o Utilisation d'un cache d'vnements...
.PP
Si vous utilisez un cache d'vnement, ou stockez tous les descripteurs
renvoys par
.BR epoll_wait (2),
alors assurez vous de disposer d'un moyen de marquer dynamiquement leurs
fermetures (causes par un vnement prcdent).
Supposons que vous recevez 100 vnements de
.BR epoll_wait (2),
et que l'vnement 47 implique de fermer le descripteur 13.
Si vous supprimez la structure et utilisez close(), alors votre cache
peut encore contenir des vnements pour ce descripteur, et poser des
problmes de cohrence.
.PP
Une solution est d'invoquer, pendant le traitement de l'vnement 47,
.BR epoll_ctl ( EPOLL_CTL_DEL )
pour supprimer le descripteur 13, le fermer, et marquer sa structure
associe comme supprime. Si vous rencontrez un autre vnement pour
le descripteur 13 dans votre traitement, vous verrez qu'il a t
supprim prcdement, sans que cela ne prte  confusion.
.PP
.SE
.SH "CONFORMIT"
.BR epoll (4)
est une API introduie dans Linux 2.5.44. Son interface devrait tre
finalise depuis le 2.5.66.
.SH "VOIR AUSSI"
.BR epoll_ctl (2),
.BR epoll_create (2),
.BR epoll_wait (2)
.SH TRADUCTION
Christophe Blaess, 2003