Up

Module Epoll

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.

Signature

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.

The implementation assumes that one never closes a file descriptor that is the domain of an Epoll.t, since doing so might remove the fd from the kernel epoll set without the implementation's knowledge.

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

val sexp_of_t : t -> Sexplib.Sexp.t
val invariant : t -> unit
val create : (num_file_descrs:int -> max_ready_events:int -> t) Core_kernel.Std.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 close : t -> unit
val find : t -> Core_unix.File_descr.t -> Flags.t option

map operations

val find_exn : t -> Core_unix.File_descr.t -> Flags.t
val set : t -> Core_unix.File_descr.t -> Flags.t -> unit
val remove : t -> Core_unix.File_descr.t -> unit
val iter : t -> f:(Core_unix.File_descr.t -> Flags.t -> unit) -> unit
val wait : t -> timeout:[
| `Never
| `Immediately
| `After of Core_kernel.Std.Time_ns.Span.t
] -> [
| `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.

With wait ~timeout:(`After span), span <= 0 is treated as 0. If span > 0, then span is rounded to the nearest millisecond, with a minimum value of 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 wait_timeout_after : t -> Core_kernel.Std.Time_ns.Span.t -> [
| `Ok
| `Timeout
]

wait_timeout_after t span = wait t ~timeout:(`After span). wait_timeout_after is a performance hack to avoid allocating `After span.

val iter_ready : t -> f:(Core_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 -> Core_unix.File_descr.t -> Flags.t -> 'a) -> 'a