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 9Structures are aligned so that any libuv handle can be cast to `uv_handle_t`. 10All API functions defined here work with any handle type. 11 12Libuv handles are not movable. Pointers to handle structures passed to 13functions must remain valid for the duration of the requested operation. Take 14care when using stack allocated handles. 15 16Data 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 88Public 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:type:`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 104API 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.. c:function:: void uv_ref(uv_handle_t* handle) 157 158 Reference the given handle. References are idempotent, that is, if a handle 159 is already referenced calling this function again will have no effect. 160 161 See :ref:`refcount`. 162 163.. c:function:: void uv_unref(uv_handle_t* handle) 164 165 Un-reference the given handle. References are idempotent, that is, if a handle 166 is not referenced calling this function again will have no effect. 167 168 See :ref:`refcount`. 169 170.. c:function:: int uv_has_ref(const uv_handle_t* handle) 171 172 Returns non-zero if the handle referenced, zero otherwise. 173 174 See :ref:`refcount`. 175 176.. c:function:: size_t uv_handle_size(uv_handle_type type) 177 178 Returns the size of the given handle type. Useful for FFI binding writers 179 who don't want to know the structure layout. 180 181 182Miscellaneous API functions 183--------------------------- 184 185The following API functions take a :c:type:`uv_handle_t` argument but they work 186just for some handle types. 187 188.. c:function:: int uv_send_buffer_size(uv_handle_t* handle, int* value) 189 190 Gets or sets the size of the send buffer that the operating 191 system uses for the socket. 192 193 If `*value` == 0, then it will set `*value` to the current send buffer size. 194 If `*value` > 0 then it will use `*value` to set the new send buffer size. 195 196 On success, zero is returned. On error, a negative result is 197 returned. 198 199 This function works for TCP, pipe and UDP handles on Unix and for TCP and 200 UDP handles on Windows. 201 202 .. note:: 203 Linux will set double the size and return double the size of the original set value. 204 205.. c:function:: int uv_recv_buffer_size(uv_handle_t* handle, int* value) 206 207 Gets or sets the size of the receive buffer that the operating 208 system uses for the socket. 209 210 If `*value` == 0, then it will set `*value` to the current receive buffer size. 211 If `*value` > 0 then it will use `*value` to set the new receive buffer size. 212 213 On success, zero is returned. On error, a negative result is 214 returned. 215 216 This function works for TCP, pipe and UDP handles on Unix and for TCP and 217 UDP handles on Windows. 218 219 .. note:: 220 Linux will set double the size and return double the size of the original set value. 221 222.. c:function:: int uv_fileno(const uv_handle_t* handle, uv_os_fd_t* fd) 223 224 Gets the platform dependent file descriptor equivalent. 225 226 The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing 227 any other handle type will fail with `UV_EINVAL`. 228 229 If a handle doesn't have an attached file descriptor yet or the handle 230 itself has been closed, this function will return `UV_EBADF`. 231 232 .. warning:: 233 Be very careful when using this function. libuv assumes it's in control of the file 234 descriptor so any change to it may lead to malfunction. 235 236.. c:function:: uv_loop_t* uv_handle_get_loop(const uv_handle_t* handle) 237 238 Returns `handle->loop`. 239 240 .. versionadded:: 1.19.0 241 242.. c:function:: void* uv_handle_get_data(const uv_handle_t* handle) 243 244 Returns `handle->data`. 245 246 .. versionadded:: 1.19.0 247 248.. c:function:: void* uv_handle_set_data(uv_handle_t* handle, void* data) 249 250 Sets `handle->data` to `data`. 251 252 .. versionadded:: 1.19.0 253 254.. c:function:: uv_handle_type uv_handle_get_type(const uv_handle_t* handle) 255 256 Returns `handle->type`. 257 258 .. versionadded:: 1.19.0 259 260.. c:function:: const char* uv_handle_type_name(uv_handle_type type) 261 262 Returns the name for the equivalent struct for a given handle type, 263 e.g. `"pipe"` (as in :c:type:`uv_pipe_t`) for `UV_NAMED_PIPE`. 264 265 If no such handle type exists, this returns `NULL`. 266 267 .. versionadded:: 1.19.0 268 269.. _refcount: 270 271Reference counting 272------------------ 273 274The libuv event loop (if run in the default mode) will run until there are no 275active `and` referenced handles left. The user can force the loop to exit early 276by unreferencing handles which are active, for example by calling :c:func:`uv_unref` 277after calling :c:func:`uv_timer_start`. 278 279A handle can be referenced or unreferenced, the refcounting scheme doesn't use 280a counter, so both operations are idempotent. 281 282All handles are referenced when active by default, see :c:func:`uv_is_active` 283for a more detailed explanation on what being `active` involves. 284