# 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.

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 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:[ `After of Core_kernel.Std.Time_ns.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`.

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

    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`.

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`.
`wait_timeout_after t span = wait t ~timeout:(`After span)`. `wait_timeout_after` is a performance hack to avoid allocating ``After span`.
`iter_ready` and `fold_ready` iterate over the ready set computed by the last call to `wait`.