Mercurial

comparison third_party/libuv/docs/src/poll.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
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.