Libuv: Buffer Sizes, File Descriptors, Handle Types, and Reference Counting

10th chunk of `runtime/doc/luvref.txt`

4a022a5502b29d6c07f60d2a17674a5dc538552872dd18a10000000100000fa4

 Gets or sets the size of the send buffer that the operating
                system uses for the socket.

                If `size` is omitted (or `0`), this will return the current
                send buffer size; otherwise, this will use `size` 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.

                Returns:
                - `integer` or `fail` (if `size` is `nil` or `0`)
                - `0` or `fail` (if `size` is not `nil` and not `0`)

                Note: Linux will set double the size and return double the
                size of the original set value.

uv.recv_buffer_size({handle} [, {size}])                 *uv.recv_buffer_size()*

                > method form `handle:recv_buffer_size([size])`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|
                - `size`: `integer` or `nil` (default: `0`)

                Gets or sets the size of the receive buffer that the operating
                system uses for the socket.

                If `size` is omitted (or `0`), this will return the current
                send buffer size; otherwise, this will use `size` 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.

                Returns:
                - `integer` or `fail` (if `size` is `nil` or `0`)
                - `0` or `fail` (if `size` is not `nil` and not `0`)

                Note: Linux will set double the size and return double the
                size of the original set value.

uv.fileno({handle})                                                *uv.fileno()*

                > method form `handle:fileno()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

                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 `EINVAL`.

                If a handle doesn't have an attached file descriptor yet or
                the handle itself has been closed, this function will return
                `EBADF`.

                Returns: `integer` or `fail`

                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.

uv.handle_get_type({handle})                              *uv.handle_get_type()*

                > method form `handle:get_type()`

                Parameters:
                - `handle`: `userdata` for sub-type of |uv_handle_t|

                Returns the name of the struct for a given handle (e.g.
                `"pipe"` for |uv_pipe_t|) and the libuv enum integer for the
                handle's type (`uv_handle_type`).

                Returns: `string, integer`

==============================================================================
REFERENCE COUNTING                                      *luv-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.

==============================================================================
`uv_timer_t` — Timer handle                          *luv-timer-handle* *uv_timer_t*

> |uv_handle_t| functions also apply.

Title: Libuv: Buffer Sizes, File Descriptors, Handle Types, and Reference Counting

Summary

This section covers libuv functions for managing handle buffer sizes (`uv.send_buffer_size`, `uv.recv_buffer_size`), obtaining file descriptors (`uv.fileno`), and determining handle types (`uv.handle_get_type`). It also provides an overview of libuv's reference counting mechanism, which controls the lifespan of the event loop based on active and referenced handles. Finally, it introduces the `uv_timer_t` handle, noting that general handle functions also apply to timers.