Libuv: Poll Handles (Continued)

watch file descriptors for readability and writability, similar to the purpose of poll(2) (https://linux.die.net/man/2/poll). 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 `uv_poll_t` for any other purpose is not recommended; |uv_tcp_t|, |uv_udp_t|, etc. provide an implementation that is faster and more scalable than what can be achieved with `uv_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 |uv.poll_stop()| or |uv.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. uv.new_poll({fd}) *uv.new_poll()* Parameters: - `fd`: `integer` Initialize the handle using a file descriptor. The file descriptor is set to non-blocking mode. Returns: `uv_poll_t userdata` or `fail` uv.new_socket_poll({fd}) *uv.new_socket_poll()* Parameters: - `fd`: `integer` Initialize the handle using a socket descriptor. On Unix this is identical to |uv.new_poll()|. On windows it takes a SOCKET handle. The socket is set to non-blocking mode. Returns: `uv_poll_t userdata` or `fail` uv.poll_start({poll}, {events}, {callback}) *uv.poll_start()* > method form `poll:start(events, callback)` Parameters: - `poll`: `uv_poll_t userdata` - `events`: `string` or `nil` (default: `"rw"`) - `callback`: `callable` - `err`: `nil` or `string` - `events`: `string` or `nil` Starts polling the file descriptor. `events` are: `"r"`, `"w"`, `"rw"`, `"d"`, `"rd"`, `"wd"`, `"rwd"`, `"p"`, `"rp"`, `"wp"`, `"rwp"`, `"dp"`, `"rdp"`, `"wdp"`, or `"rwdp"` where `r` is `READABLE`, `w` is `WRITABLE`, `d` is `DISCONNECT`, and `p` is `PRIORITIZED`. 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 user should not close the socket while the handle is active. If the user does that anyway, the callback may be called reporting an error status, but this is not guaranteed. Returns: `0` or `fail` Note Calling `uv.poll_start()` on a handle that is already active is fine. Doing so will update the events mask that is being watched for. uv.poll_stop({poll}) *uv.poll_stop()* > method form `poll:stop()` Parameters: - `poll`: `uv_poll_t userdata` Stop polling the file descriptor, the callback will no longer be called. Returns: `0` or `fail` ============================================================================== `uv_signal_t` — Signal handle *luv-signal-handle* *uv_signal_t* > |uv_handle_t|

This section continues the discussion on libuv's poll handles (`uv_poll_t`). It elaborates on using poll handles for integrating external libraries and provides warnings against misuse. The section details `uv.new_poll()`, `uv.new_socket_poll()`, `uv.poll_start()`, and `uv.poll_stop()`, including parameter descriptions and return values. It also highlights platform-specific behaviors, like Windows only supporting sockets for polling.