


EPOLL(4)            Linux Programmer's Manual            EPOLL(4)


NAME
       epoll - edge triggered I/O readiness notification facility

SYNOPSIS
       #include <sys/epoll.h>

DESCRIPTION
       Edge based variant of poll(2) which scales well  to  large
       numbers  of  watched  fds.  To set up and control an epoll
       set,   three   calls   are   provided:    epoll_create(2),
       epoll_ctl(2), epoll_wait(2).

       An  epoll  set is connected to a file descriptor, which is
       created by epoll_create(2).   Interest  for  certain  file
       descriptors   is   then   registered  using  epoll_ctl(2).
       Finally, the actual wait is then started by epoll_wait(2).

       A  good analogy is to consider epoll as a waitqueue, which
       is also like a futex. To use a waitqueue properly you have
       to do these things in the order shown:


       1.     Set the task state to stopped.

       2.     Register yourself on the waitqueue.

       3.     Check the condition.

       4.     If the condition is not met, schedule.


       epoll  is  similar.  To  wait  for  a  condition on a file
       descriptor, such as readability, you must do these  things
       in the order shown:



       1.     Register interest by using epoll_ctl (2).

       2.     Check the condition by calling read (2).

       3.     If  the  condition is not met (i.e. read() returned
              EAGAIN), call epoll_wait(2) (  i.e.  equivalent  to
              schedule).


       epoll  allows you to optimize by registering interest just
       once i.e. steps 2 and 3 may be repeated without  repeating
       step 1.

       If  you  are  concerned  about  starvation  (i.e. one file
       descriptor always has new data so others  don't  get  ser-
       viced.)  don't  be.   With  epoll  you do not have to com-
       pletely read one file descriptor until you see EAGAIN. All
       that  matters  that  until  you  see the EAGAIN, your user
       space data  structure  has  a  flag  that  says  the  file
       descriptor  is  still  readable, so another epoll event is
       not expected or required for that file descriptor.



NOTES
       epoll should not  be  regarded  as  a  faster  version  of
       poll(2) because its semantics are fundamentally different.
       Whereas poll and select(2) return immediately  if  any  of
       their  fds  are  available for reading, writing or have an
       exceptional condition, epoll only returns if  a  condition
       changes.

       Because of this, epoll should be used with non-blocking to
       avoid that a blocking read/write  will  starve  your  task
       handling  multiple  file  decriptors. The suggested way to
       use epoll is:

       i      with non-blocking file descriptors

       ii     by going to wait for an event only after read(2) or
              write(2) return EAGAIN

EXAMPLE
       In  this  example,  listener  is  a non-blocking socket on
       which listen(2) has been called. The function  do_use_fd()
       will  use  the  new  ready file descriptor until EAGAIN is
       returned by either read(2) or write(2).  An  event  driven
       state  machine  application  should, after having received
       EAGAIN, record its current state so that at the next  call
       to  do_use_fd()  will continue to read(2) or write(2) from
       where it left.

       for(;;) {
           nfds = epoll_wait(kdpfd, &pfds, -1);

           for(n = 0; n < nfds; ++n) {
               if(pfds[n].fd == s) {
                   client = accept(listener, (struct sockaddr*)&local, &addrlen);
                   if(client < 0){
                       perror("accept");
                       continue;
                   }
                   setnonblocking(client);
                   if (epoll_ctl(kdpfd, EPOLL_CTL_ADD, client, EPOLLIN) < 0) {
                       fprintf(stderr, "epoll set insertion error: fd=%d0, client);
                       return -1;
                   }
               }
               else
                   do_use_fd(pfds[n].fd);
           }
       }

       For performance reasons it is possible  to  add  the  file
       descriptor inside the epoll interface ( EPOLL_CTL_ADD
        )  once by specifying (EPOLLIN | EPOLLOUT) without having
       to continuously switch between EPOLLIN and EPOLLOUT  call-
       ing epoll_ctl(2) with EPOLL_CTL_ADD.

CONFORMING TO
       epoll(4) is a new API introduced in Linux kernel 2.5.44.

SEE ALSO
       epoll_create(2) epoll_ctl(2) epoll_wait(2)




Linux                    23 October 2002                        1
