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 `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 185Miscellaneous API functions 186--------------------------- 187 188The following API functions take a :c:type:`uv_handle_t` argument but they work 189just 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 274Reference counting 275------------------ 276 277The libuv event loop (if run in the default mode) will run until there are no 278active `and` referenced handles left. The user can force the loop to exit early 279by unreferencing handles which are active, for example by calling :c:func:`uv_unref` 280after calling :c:func:`uv_timer_start`. 281 282A handle can be referenced or unreferenced, the refcounting scheme doesn't use 283a counter, so both operations are idempotent. 284 285All handles are referenced when active by default, see :c:func:`uv_is_active` 286for a more detailed explanation on what being `active` involves. 287
