|
160
|
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.
|
