|
160
|
1
|
|
|
2 .. _poll:
|
|
|
3
|
|
|
4 :c:type:`uv_poll_t` --- Poll handle
|
|
|
5 ===================================
|
|
|
6
|
|
|
7 Poll handles are used to watch file descriptors for readability,
|
|
|
8 writability and disconnection similar to the purpose of :man:`poll(2)`.
|
|
|
9
|
|
|
10 The purpose of poll handles is to enable integrating external libraries that
|
|
|
11 rely on the event loop to signal it about the socket status changes, like
|
|
|
12 c-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
|
|
|
14 more scalable than what can be achieved with :c:type:`uv_poll_t`, especially on
|
|
|
15 Windows.
|
|
|
16
|
|
|
17 It is possible that poll handles occasionally signal that a file descriptor is
|
|
|
18 readable or writable even when it isn't. The user should therefore always
|
|
|
19 be prepared to handle EAGAIN or equivalent when it attempts to read from or
|
|
|
20 write to the fd.
|
|
|
21
|
|
|
22 It is not okay to have multiple active poll handles for the same socket, this
|
|
|
23 can cause libuv to busyloop or otherwise malfunction.
|
|
|
24
|
|
|
25 The user should not close a file descriptor while it is being polled by an
|
|
|
26 active poll handle. This can cause the handle to report an error,
|
|
|
27 but it might also start polling another socket. However the fd can be safely
|
|
|
28 closed 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
|
|
|
37 Data 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:enum:: 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
|
|
|
62 Public members
|
|
|
63 ^^^^^^^^^^^^^^
|
|
|
64
|
|
|
65 N/A
|
|
|
66
|
|
|
67 .. seealso:: The :c:type:`uv_handle_t` members also apply.
|
|
|
68
|
|
|
69
|
|
|
70 API
|
|
|
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.
|
