7.5 Polling for events on file descriptors

For details on the API we should refer to the following manual pages: epoll(7), epoll_create(2), epoll_ctl(2), epoll_wait(2). The following bindings are exported by the (vicare linux) library.

Function: epoll-create

Function: epoll-create size

Function: epoll-create1 flags

Interfaces to the C language functions epoll_create() and epoll_create1(). Open an epoll descriptor and return it as fixnum. When size is not used: it defaults to 16. If an error occurs: raise an exception.

Function: epoll-ctl epfd op fd

Function: epoll-ctl epfd op fd event

Interface to the C language function epoll_ctl(). Control interface for an epoll descriptor. Return unspecified values. If an error occurs: raise an exception.

epfd is the return value of a previous call to epoll-create. op is a fixnum representing an OR combination of flags: EPOLL_CTL_ADD, EPOLL_CTL_MOD, EPOLL_CTL_DEL. fd is a fixnum representing the file descriptor subject of the action. event is a pointer object referencing a struct epoll_event; when event is #f or not used: it defaults to the NULL pointer.

Function: epoll-wait epfd event maxevents timeout-ms

Interface to the C language function epoll_wait(). Wait for an I/O event on an epoll descriptor. Return a fixnum representing the number of file descriptors ready for the requested events; the return value is zero if no file descriptors are ready. If an error occurs: raise an exception.

epfd is the return value of a previous call to epoll-create. event is a poiner object referencing an array of struct epoll_event holding maxevents entries; maxevents is a non–negative fixnum. timeout-ms is an exact integer in the range of a C language int, it represents a timeout time in milliseconds; when set to -1 causes the call to block until at least one file descriptor is ready.

To allow for faster operations, the struct epoll_event instances handled by the epoll functions are meant to be allocated on raw memory.

Function: epoll-event-alloc number-of-entries

Allocate with malloc() an array of struct epoll_event capable of holding number-of-entries structures. If successful return a pointer object, else raise an exception.

Function: epoll-event-size

Return the number of bytes needed to hold an instance of struct epoll_event.

Function: epoll-event-set-events! events-array index new-value

Function: epoll-event-ref-events events-array index

Mutator and accessor for the field events of the struct epoll_event entry at index.

Function: epoll-event-set-data-ptr! events-array index new-value

Function: epoll-event-ref-data-ptr events-array index

Mutator and accessor for the field data.ptr of the struct epoll_event entry at index.

Function: epoll-event-set-data-fd! events-array index new-value

Function: epoll-event-ref-data-fd events-array index

Mutator and accessor for the field data.fd of the struct epoll_event entry at index.

Function: epoll-event-set-data-u32! events-array index new-value

Function: epoll-event-ref-data-u32 events-array index

Mutator and accessor for the field data.u32 of the struct epoll_event entry at index.

Function: epoll-event-set-data-u64! events-array index new-value

Function: epoll-event-ref-data-u64 events-array index

Mutator and accessor for the field data.u4 of the struct epoll_event entry at index.

Here is a meaningless example showing the mechanics of the epoll API:

(import (vicare)
  (prefix (vicare linux)
          linux.)
  (prefix (vicare posix)
          px.)
  (vicare platform constants)
  (vicare language-extensions syntaxes))

(let-values (((in ou) (px.pipe)))
  (unwind-protect
      (let ((epfd (linux.epoll-create)))
        (unwind-protect
            (let ((sizeof-struct (vector (linux.epoll-event-size))))
              (with-local-storage sizeof-struct
                (lambda (event)
                  (linux.epoll-event-set-events!  event 0 EPOLLIN)
                  (linux.epoll-event-set-data-fd! event 0 in)
                  (linux.epoll-ctl epfd EPOLL_CTL_ADD in event)))
              (px.write ou '#vu8(1))
              (with-local-storage sizeof-struct
                (lambda (events)
                  (linux.epoll-wait epfd events 1 -1)
                  (linux.epoll-event-ref-data-fd events 0) ⇒ in
                  (linux.epoll-event-ref-events events 0)  ⇒ EPOLLIN
                  ))))
          (px.close epfd)))
    (px.close in)
    (px.close ou))