uv_handle_t
— Base handle¶
uv_handle_t is the base type for all libuv handle types.
Structures are aligned so that any libuv handle can be cast to uv_handle_t. All API functions defined here work with any handle type.
Data types¶
-
uv_handle_t
¶ The base libuv handle type.
-
uv_any_handle
¶ Union of all handle types.
-
void
(*uv_alloc_cb)
(uv_handle_t* handle, size_t suggested_size, uv_buf_t* buf)¶ Type definition for callback passed to
uv_read_start()
anduv_udp_recv_start()
. The user must fill the supplieduv_buf_t
structure with whatever size, as long as it’s > 0. A suggested size (65536 at the moment) is provided, but it doesn’t need to be honored. Setting the buffer’s length to 0 will trigger aUV_ENOBUFS
error in theuv_udp_recv_cb
oruv_read_cb
callback.
-
void
(*uv_close_cb)
(uv_handle_t* handle)¶ Type definition for callback passed to
uv_close()
.
API¶
-
int
uv_is_active
(const uv_handle_t* handle)¶ Returns non-zero if the handle is active, zero if it’s inactive. What “active” means depends on the type of handle:
- A uv_async_t handle is always active and cannot be deactivated, except by closing it with uv_close().
- A uv_pipe_t, uv_tcp_t, uv_udp_t, etc. handle - basically any handle that deals with i/o - is active when it is doing something that involves i/o, like reading, writing, connecting, accepting new connections, etc.
- A uv_check_t, uv_idle_t, uv_timer_t, etc. handle is active when it has been started with a call to uv_check_start(), uv_idle_start(), etc.
Rule of thumb: if a handle of type uv_foo_t has a uv_foo_start() function, then it’s active from the moment that function is called. Likewise, uv_foo_stop() deactivates the handle again.
-
int
uv_is_closing
(const uv_handle_t* handle)¶ Returns non-zero if the handle is closing or closed, zero otherwise.
Note
This function should only be used between the initialization of the handle and the arrival of the close callback.
-
void
uv_close
(uv_handle_t* handle, uv_close_cb close_cb)¶ Request handle to be closed. close_cb will be called asynchronously after this call. This MUST be called on each handle before memory is released.
Handles that wrap file descriptors are closed immediately but close_cb will still be deferred to the next iteration of the event loop. It gives you a chance to free up any resources associated with the handle.
In-progress requests, like uv_connect_t or uv_write_t, are cancelled and have their callbacks called asynchronously with status=UV_ECANCELED.
-
void
uv_ref
(uv_handle_t* handle)¶ Reference the given handle. References are idempotent, that is, if a handle is already referenced calling this function again will have no effect.
See Reference counting.
-
void
uv_unref
(uv_handle_t* handle)¶ Un-reference the given handle. References are idempotent, that is, if a handle is not referenced calling this function again will have no effect.
See Reference counting.
-
int
uv_has_ref
(const uv_handle_t* handle)¶ Returns non-zero if the handle referenced, zero otherwise.
See Reference counting.
-
size_t
uv_handle_size
(uv_handle_type type)¶ Returns the size of the given handle type. Useful for FFI binding writers who don’t want to know the structure layout.
Miscellaneous API functions¶
The following API functions take a uv_handle_t
argument but they work
just for some handle types.
-
int
uv_send_buffer_size
(uv_handle_t* handle, int* value)¶ Gets or sets the size of the send buffer that the operating system uses for the socket.
If *value == 0, it will return the current send buffer size, otherwise it will use *value to set the new send buffer size.
This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP handles on Windows.
Note
Linux will set double the size and return double the size of the original set value.
-
int
uv_recv_buffer_size
(uv_handle_t* handle, int* value)¶ Gets or sets the size of the receive buffer that the operating system uses for the socket.
If *value == 0, it will return the current receive buffer size, otherwise it will use *value to set the new receive buffer size.
This function works for TCP, pipe and UDP handles on Unix and for TCP and UDP handles on Windows.
Note
Linux will set double the size and return double the size of the original set value.
-
int
uv_fileno
(const uv_handle_t* handle, uv_os_fd_t* fd)¶ Gets the platform dependent file descriptor equivalent.
The following handles are supported: TCP, pipes, TTY, UDP and poll. Passing any other handle type will fail with UV_EINVAL.
If a handle doesn’t have an attached file descriptor yet or the handle itself has been closed, this function will return UV_EBADF.
Warning
Be very careful when using this function. libuv assumes it’s in control of the file descriptor so any change to it may lead to malfunction.
Reference counting¶
The libuv event loop (if run in the default mode) will run until there are no
active and referenced handles left. The user can force the loop to exit early
by unreferencing handles which are active, for example by calling uv_unref()
after calling uv_timer_start()
.
A handle can be referenced or unreferenced, the refcounting scheme doesn’t use a counter, so both operations are idempotent.
All handles are referenced when active by default, see uv_is_active()
for a more detailed explanation on what being active involves.