*luvref.txt*               Nvim


                    LUV REFERENCE MANUAL

                                                                        *luvref*
This file documents the Lua bindings for the LibUV library which is used for
Nvim's event-loop and is accessible from Lua via |vim.uv| (e.g., |uv.version()|
is exposed as `vim.uv.version()`).

For information about this manual, see |luv-credits|.

For further examples, see https://github.com/luvit/luv/tree/master/examples.

==============================================================================
INTRODUCTION                                                  *luv* *luv-intro* *uv*

The luv (https://github.com/luvit/luv) project provides access to the
multi-platform support library libuv (https://github.com/libuv/libuv) in Lua
code. It was primarily developed for the luvit
(https://github.com/luvit/luvit) project as the built-in `uv` module, but can
be used in other Lua environments.

More information about the core libuv library can be found at the original
libuv documentation page (https://docs.libuv.org/).

TCP Echo Server Example ~

Here is a small example showing a TCP echo server:

    >lua
    local uv = vim.uv

    local server = uv.new_tcp()
    server:bind("127.0.0.1", 1337)
    server:listen(128, function (err)
      assert(not err, err)
      local client = uv.new_tcp()
      server:accept(client)
      client:read_start(function (err, chunk)
        assert(not err, err)
        if chunk then
          client:write(chunk)
        else
          client:shutdown()
          client:close()
        end
      end)
    end)
    print("TCP server listening at 127.0.0.1 port 1337")
    uv.run() -- an explicit run call is necessary outside of luvit
<

Module Layout ~

The luv library contains a single Lua module referred to hereafter as `uv` for
simplicity. This module consists mostly of functions with names corresponding
to their original libuv versions. For example, the libuv function
`uv_tcp_bind` has a luv version at |uv.tcp_bind()|. Currently, only two
non-function fields exists: `uv.constants` and `uv.errno`, which are tables.

Functions vs Methods ~

In addition to having simple functions, luv provides an optional method-style
API. For example, `uv.tcp_bind(server, host, port)` can alternatively be
called as `server:bind(host, port)` . Note that the first argument `server`
becomes the object and `tcp_` is removed from the function name. Method forms
are documented below where they exist.

Synchronous vs Asynchronous Functions ~

Functions that accept a callback are asynchronous. These functions may
immediately return results to the caller to indicate their initial status, but
their final execution is deferred until at least the next libuv loop
iteration. After completion, their callbacks are executed with any results
passed to it.

Functions that do not accept a callback are synchronous. These functions
immediately return their results to the caller.

Some (generally FS and DNS) functions can behave either synchronously or
asynchronously. If a callback is provided to these functions, they behave
asynchronously; if no callback is provided, they behave synchronously.

Pseudo-Types ~

Some unique types are defined. These are not actual types in Lua, but they are
used here to facilitate documenting consistent behavior:
- `fail`: an assertable `nil, string, string` tuple (see |luv-error-handling|)
- `callable`: a `function`; or a `table` or `userdata` with a `__call`
  metamethod
- `buffer`: a `string` or a sequential `table` of `string`s
- `threadargs`: variable arguments (`...`) of type `nil`, `boolean`, `number`,
  `string`, or `userdata`; number of arguments limited to 9.

==============================================================================
CONTENTS                                                          *luv-contents*

This documentation is mostly a retelling of the libuv API documentation
(https://docs.libuv.org/en/v1.x/api.html) within the context