Home Explore Blog CI



neovim

14th chunk of `runtime/doc/luvref.txt`
5e9696ec4976ef9ef09b6b9c91af5e3b9e116a8ca22b8e4a0000000100000fa6
 Creates and initializes a new |uv_idle_t|. Returns the Lua
                userdata wrapping it.

                Returns: `uv_idle_t userdata`

uv.idle_start({idle}, {callback})                              *uv.idle_start()*

                > method form `idle:start(callback)`

                Parameters:
                - `idle`: `uv_idle_t userdata`
                - `callback`: `callable`

                Start the handle with the given callback.

                Returns: `0` or `fail`

uv.idle_stop({check})                                           *uv.idle_stop()*

                > method form `idle:stop()`

                Parameters:
                - `idle`: `uv_idle_t userdata`

                Stop the handle, the callback will no longer be called.

                Returns: `0` or `fail`

==============================================================================
`uv_async_t` — Async handle                          *luv-async-handle* *uv_async_t*

> |uv_handle_t| functions also apply.

Async handles allow the user to "wakeup" the event loop and get a callback
called from another thread.

    >lua
    local async
    async = uv.new_async(function()
      print("async operation ran")
      async:close()
    end)

    async:send()
<

uv.new_async({callback})                                        *uv.new_async()*

                Parameters:
                - `callback`: `callable`
                  - `...`: `threadargs` passed to/from
                    `uv.async_send(async, ...)`

                Creates and initializes a new |uv_async_t|. Returns the Lua
                userdata wrapping it.

                Returns: `uv_async_t userdata` or `fail`

                Note: Unlike other handle initialization functions, this
                immediately starts the handle.

uv.async_send({async}, {...})                                  *uv.async_send()*

                > method form `async:send(...)`

                Parameters:
                - `async`: `uv_async_t userdata`
                - `...`: `threadargs`

                Wakeup the event loop and call the async handle's callback.

                Returns: `0` or `fail`

                Note: It's safe to call this function from any thread. The
                callback will be called on the loop thread.

                WARNING: libuv will coalesce calls to `uv.async_send(async)`,
                that is, not every call to it will yield an execution of the
                callback. For example: if `uv.async_send()` is called 5 times
                in a row before the callback is called, the callback will only
                be called once. If `uv.async_send()` is called again after the
                callback was called, it will be called again.

==============================================================================
`uv_poll_t` — Poll handle                              *luv-poll-handle* *uv_poll_t*

> |uv_handle_t| functions also apply.

Poll handles are used to watch file descriptors for readability and
writability, similar to the purpose of poll(2)
(https://linux.die.net/man/2/poll).

The purpose of poll handles is to enable integrating external libraries that
rely on the event loop to signal it about the socket status changes, like
c-ares or libssh2. Using `uv_poll_t` for any other purpose is not recommended;
|uv_tcp_t|, |uv_udp_t|, etc. provide an implementation that is faster and more
scalable than what can be achieved with `uv_poll_t`, especially on Windows.

It is possible that poll handles occasionally signal that a file descriptor is
readable or writable even when it isn't. The user should therefore always be
prepared to handle EAGAIN or equivalent when it attempts to read from or write
to the fd.

It is not okay to have multiple active poll handles for the same socket, this
can cause libuv to busyloop or otherwise malfunction.

The user should not close a file descriptor while it is being polled by an
active poll handle. This can cause

Title: Libuv: Async and Poll Handles
Summary
This section details libuv's async handles (`uv_async_t`), which allow threads to wake up the event loop and execute a callback, and covers `uv.new_async()` and `uv.async_send()`. It then introduces poll handles (`uv_poll_t`), used for monitoring file descriptors for readability and writability, and cautions against using them when higher-level abstractions like `uv_tcp_t` or `uv_udp_t` are available.