1 2.. _poll: 3 4:c:type:`uv_poll_t` --- Poll handle 5=================================== 6 7Poll handles are used to watch file descriptors for readability, 8writability and disconnection similar to the purpose of :man:`poll(2)`. 9 10The purpose of poll handles is to enable integrating external libraries that 11rely on the event loop to signal it about the socket status changes, like 12c-ares or libssh2. Using uv_poll_t for any other purpose is not recommended; 13:c:type:`uv_tcp_t`, :c:type:`uv_udp_t`, etc. provide an implementation that is faster and 14more scalable than what can be achieved with :c:type:`uv_poll_t`, especially on 15Windows. 16 17It is possible that poll handles occasionally signal that a file descriptor is 18readable or writable even when it isn't. The user should therefore always 19be prepared to handle EAGAIN or equivalent when it attempts to read from or 20write to the fd. 21 22It is not okay to have multiple active poll handles for the same socket, this 23can cause libuv to busyloop or otherwise malfunction. 24 25The user should not close a file descriptor while it is being polled by an 26active poll handle. This can cause the handle to report an error, 27but it might also start polling another socket. However the fd can be safely 28closed immediately after a call to :c:func:`uv_poll_stop` or :c:func:`uv_close`. 29 30.. note:: 31 On windows only sockets can be polled with poll handles. On Unix any file 32 descriptor that would be accepted by :man:`poll(2)` can be used. 33 34.. note:: 35 On AIX, watching for disconnection is not supported. 36 37Data types 38---------- 39 40.. c:type:: uv_poll_t 41 42 Poll handle type. 43 44.. c:type:: void (*uv_poll_cb)(uv_poll_t* handle, int status, int events) 45 46 Type definition for callback passed to :c:func:`uv_poll_start`. 47 48.. c:type:: uv_poll_event 49 50 Poll event types 51 52 :: 53 54 enum uv_poll_event { 55 UV_READABLE = 1, 56 UV_WRITABLE = 2, 57 UV_DISCONNECT = 4, 58 UV_PRIORITIZED = 8 59 }; 60 61 62Public members 63^^^^^^^^^^^^^^ 64 65N/A 66 67.. seealso:: The :c:type:`uv_handle_t` members also apply. 68 69 70API 71--- 72 73.. c:function:: int uv_poll_init(uv_loop_t* loop, uv_poll_t* handle, int fd) 74 75 Initialize the handle using a file descriptor. 76 77 .. versionchanged:: 1.2.2 the file descriptor is set to non-blocking mode. 78 79.. c:function:: int uv_poll_init_socket(uv_loop_t* loop, uv_poll_t* handle, uv_os_sock_t socket) 80 81 Initialize the handle using a socket descriptor. On Unix this is identical 82 to :c:func:`uv_poll_init`. On windows it takes a SOCKET handle. 83 84 .. versionchanged:: 1.2.2 the socket is set to non-blocking mode. 85 86.. c:function:: int uv_poll_start(uv_poll_t* handle, int events, uv_poll_cb cb) 87 88 Starts polling the file descriptor. `events` is a bitmask made up of 89 UV_READABLE, UV_WRITABLE, UV_PRIORITIZED and UV_DISCONNECT. As soon as an 90 event is detected the callback will be called with `status` set to 0, and the 91 detected events set on the `events` field. 92 93 The UV_PRIORITIZED event is used to watch for sysfs interrupts or TCP out-of-band 94 messages. 95 96 The UV_DISCONNECT event is optional in the sense that it may not be 97 reported and the user is free to ignore it, but it can help optimize the shutdown 98 path because an extra read or write call might be avoided. 99 100 If an error happens while polling, `status` will be < 0 and corresponds 101 with one of the UV_E* error codes (see :ref:`errors`). The user should 102 not close the socket while the handle is active. If the user does that 103 anyway, the callback *may* be called reporting an error status, but this 104 is **not** guaranteed. 105 106 .. note:: 107 Calling :c:func:`uv_poll_start` on a handle that is already active is fine. Doing so 108 will update the events mask that is being watched for. 109 110 .. note:: 111 Though UV_DISCONNECT can be set, it is unsupported on AIX and as such will not be set 112 on the `events` field in the callback. 113 114 .. versionchanged:: 1.9.0 Added the UV_DISCONNECT event. 115 .. versionchanged:: 1.14.0 Added the UV_PRIORITIZED event. 116 117.. c:function:: int uv_poll_stop(uv_poll_t* poll) 118 119 Stop polling the file descriptor, the callback will no longer be called. 120 121.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 122