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