Mercurial

comparison third_party/libuv/docs/src/handle.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 .. _handle:
3
4 :c:type:`uv_handle_t` --- Base handle
5 =====================================
6
7 `uv_handle_t` is the base type for all libuv handle types.
8
9 Structures are aligned so that any libuv handle can be cast to `uv_handle_t`.
10 All API functions defined here work with any handle type.
11
12 Libuv handles are not movable. Pointers to handle structures passed to
13 functions must remain valid for the duration of the requested operation. Take
14 care when using stack allocated handles.
15
16 Data types
17 ----------
18
19 .. c:type:: uv_handle_t
20
21 The base libuv handle type.
22
23 .. c:enum:: uv_handle_type
24
25 The kind of the libuv handle.
26
27 ::
28
29 typedef enum {
30 UV_UNKNOWN_HANDLE = 0,
31 UV_ASYNC,
32 UV_CHECK,
33 UV_FS_EVENT,
34 UV_FS_POLL,
35 UV_HANDLE,
36 UV_IDLE,
37 UV_NAMED_PIPE,
38 UV_POLL,
39 UV_PREPARE,
40 UV_PROCESS,
41 UV_STREAM,
42 UV_TCP,
43 UV_TIMER,
44 UV_TTY,
45 UV_UDP,
46 UV_SIGNAL,
47 UV_FILE,
48 UV_HANDLE_TYPE_MAX
49 } uv_handle_type;
50
51 .. c:type:: uv_any_handle
52
53 Union of all handle types.
54
55 .. c:type:: void (*uv_alloc_cb)(uv_handle_t* handle, size_t suggested_size, uv_buf_t* buf)
56
57 Type definition for callback passed to :c:func:`uv_read_start` and
58 :c:func:`uv_udp_recv_start`. The user must allocate memory and fill the supplied
59 :c:type:`uv_buf_t` structure. If NULL is assigned as the buffer's base or 0 as its length,
60 a ``UV_ENOBUFS`` error will be triggered in the :c:type:`uv_udp_recv_cb` or the
61 :c:type:`uv_read_cb` callback.
62
63 Each buffer is used only once and the user is responsible for freeing it in the
64 :c:type:`uv_udp_recv_cb` or the :c:type:`uv_read_cb` callback.
65
66 A suggested size (65536 at the moment in most cases) is provided, but it's just an indication,
67 not related in any way to the pending data to be read. The user is free to allocate the amount
68 of memory they decide.
69
70 As an example, applications with custom allocation schemes such as using freelists, allocation
71 pools or slab based allocators may decide to use a different size which matches the memory
72 chunks they already have.
73
74 Example:
75
76 ::
77
78 static void my_alloc_cb(uv_handle_t* handle, size_t suggested_size, uv_buf_t* buf) {
79 buf->base = malloc(suggested_size);
80 buf->len = suggested_size;
81 }
82
83 .. c:type:: void (*uv_close_cb)(uv_handle_t* handle)
84
85 Type definition for callback passed to :c:func:`uv_close`.
86
87
88 Public members
89 ^^^^^^^^^^^^^^
90
91 .. c:member:: uv_loop_t* uv_handle_t.loop
92
93 Pointer to the :c:type:`uv_loop_t` the handle is running on. Readonly.
94
95 .. c:member:: uv_handle_type uv_handle_t.type
96
97 The :c:enum:`uv_handle_type`, indicating the type of the underlying handle. Readonly.
98
99 .. c:member:: void* uv_handle_t.data
100
101 Space for user-defined arbitrary data. libuv does not use this field.
102
103
104 API
105 ---
106
107 .. c:macro:: UV_HANDLE_TYPE_MAP(iter_macro)
108
109 Macro that expands to a series of invocations of `iter_macro` for
110 each of the handle types. `iter_macro` is invoked with two
111 arguments: the name of the `uv_handle_type` element without the
112 `UV_` prefix, and the name of the corresponding structure type
113 without the `uv_` prefix and `_t` suffix.
114
115 .. c:function:: int uv_is_active(const uv_handle_t* handle)
116
117 Returns non-zero if the handle is active, zero if it's inactive. What
118 "active" means depends on the type of handle:
119
120 - A uv_async_t handle is always active and cannot be deactivated, except
121 by closing it with uv_close().
122
123 - A uv_pipe_t, uv_tcp_t, uv_udp_t, etc. handle - basically any handle that
124 deals with i/o - is active when it is doing something that involves i/o,
125 like reading, writing, connecting, accepting new connections, etc.
126
127 - A uv_check_t, uv_idle_t, uv_timer_t, etc. handle is active when it has
128 been started with a call to uv_check_start(), uv_idle_start(), etc.
129
130 Rule of thumb: if a handle of type `uv_foo_t` has a `uv_foo_start()`
131 function, then it's active from the moment that function is called.
132 Likewise, `uv_foo_stop()` deactivates the handle again.
133
134 .. c:function:: int uv_is_closing(const uv_handle_t* handle)
135
136 Returns non-zero if the handle is closing or closed, zero otherwise.
137
138 .. note::
139 This function should only be used between the initialization of the handle and the
140 arrival of the close callback.
141
142 .. c:function:: void uv_close(uv_handle_t* handle, uv_close_cb close_cb)
143
144 Request handle to be closed. `close_cb` will be called asynchronously after
145 this call. This MUST be called on each handle before memory is released.
146 Moreover, the memory can only be released in `close_cb` or after it has
147 returned.
148
149 Handles that wrap file descriptors are closed immediately but
150 `close_cb` will still be deferred to the next iteration of the event loop.
151 It gives you a chance to free up any resources associated with the handle.
152
153 In-progress requests, like uv_connect_t or uv_write_t, are cancelled and
154 have their callbacks called asynchronously with status=UV_ECANCELED.
155
156 `close_cb` can be `NULL` in cases where no cleanup or deallocation is
157 necessary.
158
159 .. c:function:: void uv_ref(uv_handle_t* handle)
160
161 Reference the given handle. References are idempotent, that is, if a handle
162 is already referenced calling this function again will have no effect.
163
164 See :ref:`refcount`.
165
166 .. c:function:: void uv_unref(uv_handle_t* handle)
167
168 Un-reference the given handle. References are idempotent, that is, if a handle
169 is not referenced calling this function again will have no effect.
170
171 See :ref:`refcount`.
172
173 .. c:function:: int uv_has_ref(const uv_handle_t* handle)
174
175 Returns non-zero if the handle referenced, zero otherwise.
176
177 See :ref:`refcount`.
178
179 .. c:function:: size_t uv_handle_size(uv_handle_type type)
180
181 Returns the size of the given handle type. Useful for FFI binding writers
182 who don't want to know the structure layout.
183
184
185 Miscellaneous API functions
186 ---------------------------
187
188 The following API functions take a :c:type:`uv_handle_t` argument but they work
189 just for some handle types.
190
191 .. c:function:: int uv_send_buffer_size(uv_handle_t* handle, int* value)
192
193 Gets or sets the size of the send buffer that the operating
194 system uses for the socket.
195
196 If `*value` == 0, then it will set `*value` to the current send buffer size.
197 If `*value` > 0 then it will use `*value` to set the new send buffer size.
198
199 On success, zero is returned. On error, a negative result is
200 returned.
201
202 This function works for TCP, pipe and UDP handles on Unix and for TCP and
203 UDP handles on Windows.
204
205 .. note::
206 Linux will set double the size and return double the size of the original set value.
207
208 .. c:function:: int uv_recv_buffer_size(uv_handle_t* handle, int* value)
209
210 Gets or sets the size of the receive buffer that the operating
211 system uses for the socket.
212
213 If `*value` == 0, then it will set `*value` to the current receive buffer size.
214 If `*value` > 0 then it will use `*value` to set the new receive buffer size.
215
216 On success, zero is returned. On error, a negative result is
217 returned.
218
219 This function works for TCP, pipe and UDP handles on Unix and for TCP and
220 UDP handles on Windows.
221
222 .. note::
223 Linux will set double the size and return double the size of the original set value.
224
225 .. c:function:: int uv_fileno(const uv_handle_t* handle, uv_os_fd_t* fd)
226
227 Gets the platform dependent file descriptor equivalent.
228
229 The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing
230 any other handle type will fail with `UV_EINVAL`.
231
232 If a handle doesn't have an attached file descriptor yet or the handle
233 itself has been closed, this function will return `UV_EBADF`.
234
235 .. warning::
236 Be very careful when using this function. libuv assumes it's in control of the file
237 descriptor so any change to it may lead to malfunction.
238
239 .. c:function:: uv_loop_t* uv_handle_get_loop(const uv_handle_t* handle)
240
241 Returns `handle->loop`.
242
243 .. versionadded:: 1.19.0
244
245 .. c:function:: void* uv_handle_get_data(const uv_handle_t* handle)
246
247 Returns `handle->data`.
248
249 .. versionadded:: 1.19.0
250
251 .. c:function:: void uv_handle_set_data(uv_handle_t* handle, void* data)
252
253 Sets `handle->data` to `data`.
254
255 .. versionadded:: 1.19.0
256
257 .. c:function:: uv_handle_type uv_handle_get_type(const uv_handle_t* handle)
258
259 Returns `handle->type`.
260
261 .. versionadded:: 1.19.0
262
263 .. c:function:: const char* uv_handle_type_name(uv_handle_type type)
264
265 Returns the name for the equivalent struct for a given handle type,
266 e.g. `"pipe"` (as in :c:type:`uv_pipe_t`) for `UV_NAMED_PIPE`.
267
268 If no such handle type exists, this returns `NULL`.
269
270 .. versionadded:: 1.19.0
271
272 .. _refcount:
273
274 Reference counting
275 ------------------
276
277 The libuv event loop (if run in the default mode) will run until there are no
278 active `and` referenced handles left. The user can force the loop to exit early
279 by unreferencing handles which are active, for example by calling :c:func:`uv_unref`
280 after calling :c:func:`uv_timer_start`.
281
282 A handle can be referenced or unreferenced, the refcounting scheme doesn't use
283 a counter, so both operations are idempotent.
284
285 All handles are referenced when active by default, see :c:func:`uv_is_active`
286 for a more detailed explanation on what being `active` involves.