Module Linux_ext.Epoll

module Epoll: sig .. end
epoll() - a linux I/O multiplexer of the same family as select() or poll(). Its main differences are support for Edge or Level triggered notifications (We're using Level-triggered to emulate select) and much better scaling with the number of file descriptors.

See the man pages for a full description of the epoll facility.


module Flags: sig .. end
type t 
An Epoll.t maintains a map from File_descr.t to Flags.t, where the domain is the set of file descriptors that one is interested in, and the flags associated with each file descriptor specify the types of events one is interested in being notified about for that file descriptor. Our implementation maintains a user-level table equivalent to the kernel epoll set, so that sexp_of_t produces useful human-readable information, and so that we can present our standard table interface.

An Epoll.t also has a buffer that is used to store the set of ready fds returned by calling wait.

val invariant : t -> unit
val create : (num_file_descrs:int -> max_ready_events:int -> t) Or_error.t
create ~num_file_descrs creates a new epoll set able to watch file descriptors in [0, num_file_descrs). Additionally, the set allocates space for reading the ready events when wait returns, allowing for up to max_ready_events to be returned in a single call to wait.
val find : t -> Unix.File_descr.t -> Flags.t option
map operations
val find_exn : t -> Unix.File_descr.t -> Flags.t
val set : t ->
Unix.File_descr.t -> Flags.t -> unit
val remove : t -> Unix.File_descr.t -> unit
val iter : t ->
f:(Unix.File_descr.t -> Flags.t -> unit) -> unit
val wait : t ->
timeout:[ `After of Span.t | `Immediately | `Never ] -> [ `Ok | `Timeout ]
wait t ~timeout blocks until at least one file descriptor in t is ready for one of the events it is being watched for, or timeout passes. wait side effects t by storing the ready set in it. One can subsequently access the ready set by calling iter_ready or fold_ready.

The timeout has a granularity of one millisecond. wait rounds up the timeout to the next millisecond. E.g. a timeout of one microsecond will be rounded up to one millisecond.

Note that this method should not be considered thread safe. There is mutable state in t that will be changed by invocations to wait that cannot be prevented by mutexes around wait.

val iter_ready : t ->
f:(Unix.File_descr.t -> Flags.t -> unit) -> unit
iter_ready and fold_ready iterate over the ready set computed by the last call to wait.
val fold_ready : t ->
init:'a ->
f:('a -> Unix.File_descr.t -> Flags.t -> 'a) -> 'a
val sexp_of_t : t -> Sexplib.Sexp.t

create ~num_file_descrs creates a new epoll set able to watch file descriptors in [0, num_file_descrs). Additionally, the set allocates space for reading the ready events when wait returns, allowing for up to max_ready_events to be returned in a single call to wait.

map operations

wait t ~timeout blocks until at least one file descriptor in t is ready for one of the events it is being watched for, or timeout passes. wait side effects t by storing the ready set in it. One can subsequently access the ready set by calling iter_ready or fold_ready.

The timeout has a granularity of one millisecond. wait rounds up the timeout to the next millisecond. E.g. a timeout of one microsecond will be rounded up to one millisecond.

Note that this method should not be considered thread safe. There is mutable state in t that will be changed by invocations to wait that cannot be prevented by mutexes around wait.

iter_ready and fold_ready iterate over the ready set computed by the last call to wait.