Module Uwt.Poll

module Poll: sig .. end

Poll handles are used to watch file descriptors for readability, writability and disconnection similar to the purpose of poll(2).

The purpose of poll handles is to enable integrating external libraries that rely on the event loop to signal it about the socket status changes, like c-ares or libssh2. Using Poll.t for any other purpose is not recommended; Uwt.Tcp.t, Uwt.Udp.t, etc. provide an implementation that is faster and more scalable than what can be achieved with Uwt.Poll.t, especially on Windows.

It is possible that poll handles occasionally signal that a file descriptor is readable or writable even when it isn't. The user should therefore always be prepared to handle EAGAIN or equivalent when it attempts to read from or write to the fd.

It is not okay to have multiple active poll handles for the same socket, this can cause libuv to busyloop or otherwise malfunction.

The user should not close a file descriptor while it is being polled by an active poll handle. This can cause the handle to report an error, but it might also start polling another socket. However the fd can be safely closed immediately after a call to close.

Note: On windows only sockets can be polled with poll handles. On Unix any file descriptor that would be accepted by poll(2) can be used.

Note: On AIX, watching for disconnection is not supported.

type t

include Uwt.Handle

include Uwt.Handle_fileno

val to_handle : t -> Uwt.Handle.t

type event =

`\|`	`Readable`
`\|`	`Writable`
`\|`	`Disconnect`
`\|`	`Prioritized`

val start : Unix.file_descr ->
       event list ->
       cb:(t -> event list uv_result -> unit) ->
       t uv_result

Starts polling the file descriptor. events is a list of Readable, Writable and Disconnect. As soon as an event is detected the callback will be called with status set to 0, and the detected events set on the events field.

The Disconnect event is optional in the sense that it may not be reported and the user is free to ignore it, but it can help optimize the shutdown path because an extra read or write call might be avoided.

val start_exn : Unix.file_descr ->
       event list ->
       cb:(t -> event list uv_result -> unit) -> t

val update_events : t -> event list -> Int_result.unit

Update the events mask that is being watched for

val update_events_exn : t -> event list -> unit