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 90 as an event is detected the callback will be called with `status` set to 0, 91 and the detected events set on the `events` field. 92 93 The `UV_PRIORITIZED` event is used to watch for sysfs interrupts or TCP 94 out-of-band 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 98 shutdown 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 is 104 **not** guaranteed. 105 106 .. note:: 107 Calling :c:func:`uv_poll_start` on a handle that is already active is 108 fine. Doing so 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 112 will not be set on the `events` field in the callback. 113 114 .. note:: 115 If one of the events `UV_READABLE` or `UV_WRITABLE` are set, the 116 callback will be called again, as long as the given fd/socket remains 117 readable or writable accordingly. Particularly in each of the following 118 scenarios: 119 120 * The callback has been called because the socket became 121 readable/writable and the callback did not conduct a read/write on 122 this socket at all. 123 * The callback committed a read on the socket, and has not read all the 124 available data (when `UV_READABLE` is set). 125 * The callback committed a write on the socket, but it remained 126 writable afterwards (when `UV_WRITABLE` is set). 127 * The socket has already became readable/writable before calling 128 :c:func:`uv_poll_start` on a poll handle associated with this socket, 129 and since then the state of the socket did not changed. 130 131 In all of the above listed scenarios, the socket remains readable or 132 writable and hence the callback will be called again (depending on the 133 events set in the bitmask). This behaviour is known as level 134 triggering. 135 136 .. versionchanged:: 1.9.0 Added the `UV_DISCONNECT` event. 137 .. versionchanged:: 1.14.0 Added the `UV_PRIORITIZED` event. 138 139.. c:function:: int uv_poll_stop(uv_poll_t* poll) 140 141 Stop polling the file descriptor, the callback will no longer be called. 142 143 .. note:: 144 Calling :c:func:`uv_poll_stop` is effective immediately: any pending 145 callback is also canceled, even if the socket state change notification 146 was already pending. 147 148.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 149