Merge remote-tracking branch 'upstream/master' into colorcolcharcolorcolchar

1 files changed, 318 insertions, 38 deletions

diff --git a/runtime/doc/luvref.txt b/runtime/doc/luvref.txt
index 859e75e4af..915b69efe3 100644
--- a/runtime/doc/luvref.txt
+++ b/runtime/doc/luvref.txt
@@ -3,10 +3,10 @@
 
                     LUV REFERENCE MANUAL
 
-								      *luvref*
+                                                                        *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.loop| (e.g., |uv.version()|
-is exposed as `vim.loop.version()`).
+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|.
 
@@ -24,12 +24,12 @@ 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~
+TCP Echo Server Example ~
 
 Here is a small example showing a TCP echo server:
 
     >lua
-    local uv = vim.loop
+    local uv = vim.uv
 
     local server = uv.new_tcp()
     server:bind("127.0.0.1", 1337)
@@ -51,15 +51,15 @@ Here is a small example showing a TCP echo server:
     uv.run() -- an explicit run call is necessary outside of luvit
 <
 
-Module Layout~
+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 one
-non-function field exists: `uv.constants`, which is a table.
+`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~
+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
@@ -67,7 +67,7 @@ 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~
+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
@@ -82,7 +82,7 @@ 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~
+Pseudo-Types ~
 
 Some unique types are defined. These are not actual types in Lua, but they are
 used here to facilitate documenting consistent behavior:
@@ -91,7 +91,7 @@ used here to facilitate documenting consistent behavior:
   metamethod
 - `buffer`: a `string` or a sequential `table` of `string`s
 - `threadargs`: variable arguments (`...`) of type `nil`, `boolean`, `number`,
-  `string`, or `userdata`
+  `string`, or `userdata`; number of arguments limited to 9.
 
 ==============================================================================
 CONTENTS                                                          *luv-contents*
@@ -133,10 +133,10 @@ module.
 ==============================================================================
 ERROR HANDLING                                              *luv-error-handling*
 
-In libuv, errors are negative numbered constants; however, these errors and
-the functions used to handle them are not exposed to luv users. Instead, if an
-internal error is encountered, the luv function will return to the caller an
-assertable `nil, err, name` tuple.
+In libuv, errors are negative numbered constants; however, while those errors
+are exposed through `uv.errno`, the functions used to handle them are not
+exposed to luv users. Instead, if an internal error is encountered, the luv
+function will return to the caller an assertable `nil, err, name` tuple.
 
 - `nil` idiomatically indicates failure
 - `err` is a string with the format `{name}: {message}`
@@ -151,6 +151,94 @@ When a function is called successfully, it will return either a value that is
 relevant to the operation of the function, or the integer `0` to indicate
 success, or sometimes nothing at all. These cases are documented below.
 
+`uv.errno`                                                              *uv.errno*
+
+A table value which exposes error constants as a map, where the key is the
+error name (without the `UV_` prefix) and its value is a negative number.
+See Libuv's "Error constants" page for further details.
+(https://docs.libuv.org/en/v1.x/errors.html#error-constants)
+
+- `E2BIG`: argument list too long.
+- `EACCES`: permission denied.
+- `EADDRINUSE`: address already in use.
+- `EADDRNOTAVAIL`: address not available.
+- `EAFNOSUPPORT`: address family not supported.
+- `EAGAIN`: resource temporarily unavailable.
+- `EAI_ADDRFAMILY`: address family not supported.
+- `EAI_AGAIN`: temporary failure.
+- `EAI_BADFLAGS`: bad ai_flags value.
+- `EAI_BADHINTS`: invalid value for hints.
+- `EAI_CANCELED`: request canceled.
+- `EAI_FAIL`: permanent failure.
+- `EAI_FAMILY`: ai_family not supported.
+- `EAI_MEMORY`: out of memory.
+- `EAI_NODATA`: no address.
+- `EAI_NONAME`: unknown node or service.
+- `EAI_OVERFLOW`: argument buffer overflow.
+- `EAI_PROTOCOL`: resolved protocol is unknown.
+- `EAI_SERVICE`: service not available for socket type.
+- `EAI_SOCKTYPE`: socket type not supported.
+- `EALREADY`: connection already in progress.
+- `EBADF`: bad file descriptor.
+- `EBUSY`: resource busy or locked.
+- `ECANCELED`: operation canceled.
+- `ECHARSET`: invalid Unicode character.
+- `ECONNABORTED`: software caused connection abort.
+- `ECONNREFUSED`: connection refused.
+- `ECONNRESET`: connection reset by peer.
+- `EDESTADDRREQ`: destination address required.
+- `EEXIST`: file already exists.
+- `EFAULT`: bad address in system call argument.
+- `EFBIG`: file too large.
+- `EHOSTUNREACH`: host is unreachable.
+- `EINTR`: interrupted system call.
+- `EINVAL`: invalid argument.
+- `EIO`: i/o error.
+- `EISCONN`: socket is already connected.
+- `EISDIR`: illegal operation on a directory.
+- `ELOOP`: too many symbolic links encountered.
+- `EMFILE`: too many open files.
+- `EMSGSIZE`: message too long.
+- `ENAMETOOLONG`: name too long.
+- `ENETDOWN`: network is down.
+- `ENETUNREACH`: network is unreachable.
+- `ENFILE`: file table overflow.
+- `ENOBUFS`: no buffer space available.
+- `ENODEV`: no such device.
+- `ENOENT`: no such file or directory.
+- `ENOMEM`: not enough memory.
+- `ENONET`: machine is not on the network.
+- `ENOPROTOOPT`: protocol not available.
+- `ENOSPC`: no space left on device.
+- `ENOSYS`: function not implemented.
+- `ENOTCONN`: socket is not connected.
+- `ENOTDIR`: not a directory.
+- `ENOTEMPTY`: directory not empty.
+- `ENOTSOCK`: socket operation on non-socket.
+- `ENOTSUP`: operation not supported on socket.
+- `EOVERFLOW`: value too large for defined data type.
+- `EPERM`: operation not permitted.
+- `EPIPE`: broken pipe.
+- `EPROTO`: protocol error.
+- `EPROTONOSUPPORT`: protocol not supported.
+- `EPROTOTYPE`: protocol wrong type for socket.
+- `ERANGE`: result too large.
+- `EROFS`: read-only file system.
+- `ESHUTDOWN`: cannot send after transport endpoint shutdown.
+- `ESPIPE`: invalid seek.
+- `ESRCH`: no such process.
+- `ETIMEDOUT`: connection timed out.
+- `ETXTBSY`: text file is busy.
+- `EXDEV`: cross-device link not permitted.
+- `UNKNOWN`: unknown error.
+- `EOF`: end of file.
+- `ENXIO`: no such device or address.
+- `EMLINK`: too many links.
+- `ENOTTY`: inappropriate ioctl for device.
+- `EFTYPE`: inappropriate file type or format.
+- `EILSEQ`: illegal byte sequence.
+- `ESOCKTNOSUPPORT`: socket type not supported.
+
 ==============================================================================
 VERSION CHECKING                                          *luv-version-checking*
 
@@ -1213,11 +1301,11 @@ uv.spawn({path}, {options}, {on_exit})                              *uv.spawn()*
                 The `options` table accepts the following fields:
 
                   - `options.args` - Command line arguments as a list of
-                    string. The first string should be the path to the
-                    program. On Windows, this uses CreateProcess which
-                    concatenates the arguments into a string. This can cause
-                    some strange errors. (See `options.verbatim` below for
-                    Windows.)
+                    strings. The first string should not be the path to the
+                    program, since that is already provided via `path`. On
+                    Windows, this uses CreateProcess which concatenates the
+                    arguments into a string. This can cause some strange
+                    errors (see `options.verbatim` below for Windows).
                   - `options.stdio` - Set the file descriptors that will be
                     made available to the child process. The convention is
                     that the first entries are stdin, stdout, and stderr.
@@ -1267,7 +1355,7 @@ uv.process_kill({process}, {signum})                         *uv.process_kill()*
 
                 Parameters:
                 - `process`: `uv_process_t userdata`
-                - `signum`: `integer` or `string`
+                - `signum`: `integer` or `string` or `nil` (default: `sigterm`)
 
                 Sends the specified signal to the given process handle. Check
                 the documentation on |uv_signal_t| for signal support,
@@ -1279,7 +1367,7 @@ uv.kill({pid}, {signum})                                             *uv.kill()*
 
                 Parameters:
                 - `pid`: `integer`
-                - `signum`: `integer` or `string`
+                - `signum`: `integer` or `string` or `nil` (default: `sigterm`)
 
                 Sends the specified signal to the given PID. Check the
                 documentation on |uv_signal_t| for signal support, specially
@@ -1976,6 +2064,69 @@ uv.pipe({read_flags}, {write_flags})                                 *uv.pipe()*
                     end)
 <
 
+uv.pipe_bind2({pipe}, {name}, {flags})                         *uv.pipe_bind2()*
+
+                > method form `pipe:pipe_bind(name, flags)`
+	
+                Parameters:
+                - `pipe`: `uv_pipe_t userdata`
+                - `name`: `string`
+                - `flags`: `integer` or `table` or `nil`(default: 0)
+
+                Flags:
+                 - If `type(flags)` is `number`, it must be `0` or
+                   `uv.constants.PIPE_NO_TRUNCATE`.
+                 - If `type(flags)` is `table`, it must be `{}` or
+                   `{ no_trunate = true|false }`.
+                 - If `type(flags)` is `nil`, it use default value `0`.
+                 - Returns `EINVAL` for unsupported flags without performing the
+                   bind.
+
+                Bind the pipe to a file path (Unix) or a name (Windows).
+
+                Supports Linux abstract namespace sockets. namelen must include
+                the leading '\0' byte but not the trailing nul byte.
+
+                Returns: `0` or `fail`
+
+                *Note*:
+                1. Paths on Unix get truncated to sizeof(sockaddr_un.sun_path)
+                   bytes, typically between 92 and 108 bytes.
+                2. New in version 1.46.0.
+
+uv.pipe_connect2(pipe, name, [flags], [callback])           *uv.pipe_connect2()*
+
+                > method form `pipe:connect2(name, [flags], [callback])`
+
+                Parameters:
+                - `pipe`: `uv_pipe_t userdata`
+                - `name`: `string`
+                - `flags`: `integer` or `table` or `nil`(default: 0)
+                - `callback`: `callable` or `nil`
+                  - `err`: `nil` or `string`
+
+                `Flags`:
+
+                - If `type(flags)` is `number`, it must be `0` or
+                  `uv.constants.PIPE_NO_TRUNCATE`.
+                - If `type(flags)` is `table`, it must be `{}` or
+                  `{ no_trunate = true|false }`.
+                - If `type(flags)` is `nil`, it use default value `0`.
+                - Returns `EINVAL` for unsupported flags without performing the
+                  bind operation.
+
+                Connect to the Unix domain socket or the named pipe.
+
+                Supports Linux abstract namespace sockets. namelen must include
+                the leading nul byte but not the trailing nul byte.
+
+                Returns: `uv_connect_t userdata` or `fail`
+
+                *Note*:
+                1. Paths on Unix get truncated to sizeof(sockaddr_un.sun_path)
+                   bytes, typically between 92 and 108 bytes.
+                2. New in version 1.46.0.
+
 ==============================================================================
 `uv_tty_t` — TTY handle                                  *luv-tty-handle* *uv_tty_t*
 
@@ -2488,7 +2639,7 @@ uv.fs_poll_start({fs_poll}, {path}, {interval}, {callback}) *uv.fs_poll_start()*
                 > method form `fs_poll:start(path, interval, callback)`
 
                 Parameters:
-                - `fs_event`: `uv_fs_event_t userdata`
+                - `fs_poll`: `uv_fs_poll_t userdata`
                 - `path`: `string`
                 - `interval`: `integer`
                 - `callback`: `callable`
@@ -2829,7 +2980,7 @@ uv.fs_fstat({fd} [, {callback}])                                 *uv.fs_fstat()*
 uv.fs_lstat({path} [, {callback}])                               *uv.fs_lstat()*
 
                 Parameters:
-                - `fd`: `integer`
+                - `path`: `string`
                 - `callback`: `callable` (async version) or `nil` (sync
                   version)
                   - `err`: `nil` or `string`
@@ -3272,14 +3423,17 @@ file system operations, as well as `getaddrinfo` and `getnameinfo` requests.
 uv.new_work({work_callback}, {after_work_callback})              *uv.new_work()*
 
                 Parameters:
-                - `work_callback`: `function`
+                - `work_callback`: `function` or `string`
                   - `...`: `threadargs` passed to/from
                     `uv.queue_work(work_ctx, ...)`
                 - `after_work_callback`: `function`
                   - `...`: `threadargs` returned from `work_callback`
 
                 Creates and initializes a new `luv_work_ctx_t` (not
-                `uv_work_t`). Returns the Lua userdata wrapping it.
+                `uv_work_t`).
+                `work_callback` is a Lua function or a string containing Lua
+                code or bytecode dumped from a function. Returns the Lua
+                userdata wrapping it.
 
                 Returns: `luv_work_ctx_t userdata`
 
@@ -3380,19 +3534,22 @@ uv.new_thread([{options}, ] {entry}, {...})                    *uv.new_thread()*
                 Parameters:
                 - `options`: `table` or `nil`
                   - `stack_size`: `integer` or `nil`
-                - `entry`: `function`
+                - `entry`: `function` or `string`
                 - `...`: `threadargs` passed to `entry`
 
                 Creates and initializes a `luv_thread_t` (not `uv_thread_t`).
                 Returns the Lua userdata wrapping it and asynchronously
-                executes `entry`, which can be either a Lua function or a Lua
-                function dumped to a string. Additional arguments `...` are
-                passed to the `entry` function and an optional `options` table
-                may be provided. Currently accepted `option` fields are
-                `stack_size`.
+                executes `entry`, which can be either a Lua function or a
+                string containing Lua code or bytecode dumped from a function.
+                Additional arguments `...` are passed to the `entry` function
+                and an optional `options` table may be provided. Currently
+                accepted `option` fields are `stack_size`.
 
                 Returns: `luv_thread_t userdata` or `fail`
 
+                Note: unsafe, please make sure that the thread's end of life
+                is before Lua state is closed.
+
 uv.thread_equal({thread}, {other_thread})                    *uv.thread_equal()*
 
                 > method form `thread:equal(other_thread)`
@@ -3405,6 +3562,73 @@ uv.thread_equal({thread}, {other_thread})                    *uv.thread_equal()*
                 This function is equivalent to the `__eq` metamethod.
 
                 Returns: `boolean`
+                                                     *uv.thread_setaffinity()*
+uv.thread_setaffinity({thread}, {affinity} [, {get_old_affinity}])
+
+                > method form `thread:setaffinity(affinity, [get_old_affinity])`
+
+                Parameters:
+                - `thread`: `luv_thread_t userdata`
+                - `affinity`: `table`
+                  - `[1, 2, 3, ..., n]` : `boolean`
+                - `get_old_affinity`: `boolean`
+
+                Sets the specified thread's affinity setting.
+
+                `affinity` must be a table where each of the keys are a CPU
+                number and the values are booleans that represent whether the
+                `thread` should be eligible to run on that CPU. If the length
+                of the `affinity` table is not greater than or equal to
+                |uv.cpumask_size()|, any CPU numbers missing from the table
+                will have their affinity set to `false`. If setting the
+                affinity of more than |uv.cpumask_size()| CPUs is desired,
+                `affinity` must be an array-like table with no gaps, since
+                `#affinity` will be used as the `cpumask_size` if it is
+                greater than |uv.cpumask_size()|.
+
+                If `get_old_affinity` is `true`, the previous affinity
+                settings for the `thread` will be returned. Otherwise, `true`
+                is returned after a successful call.
+
+                Note: Thread affinity setting is not atomic on Windows.
+                Unsupported on macOS.
+
+                Returns: `table` or `boolean` or `fail`
+                - `[1, 2, 3, ..., n]` : `boolean`
+
+
+uv.thread_getaffinity({thread} [, {mask_size}])        *uv.thread_getaffinity()*
+
+                > method form `thread:getaffinity([mask_size])`
+
+                Parameters:
+                - `thread`: `luv_thread_t userdata`
+                - `mask_size`: `integer`
+
+                Gets the specified thread's affinity setting.
+
+                If `mask_size` is provided, it must be greater than or equal
+                to `uv.cpumask_size()`. If the `mask_size` parameter is
+                omitted, then the return of `uv.cpumask_size()` will be used.
+                Returns an array-like table where each of the keys correspond
+                to a CPU number and the values are booleans that represent
+                whether the `thread` is eligible to run on that CPU.
+
+                Note: Thread affinity getting is not atomic on Windows.
+                Unsupported on macOS.
+
+                Returns: `table` or `fail`
+                - `[1, 2, 3, ..., n]` : `boolean`
+
+uv.thread_getcpu()                                          *uv.thread_getcpu()*
+
+                Gets the CPU number on which the calling thread is running.
+
+                Note: The first CPU will be returned as the number 1, not 0.
+                This allows for the number to correspond with the table keys
+                used in `uv.thread_getaffinity` and `uv.thread_setaffinity`.
+
+                Returns: `integer` or `fail`
 
 uv.thread_self()                                              *uv.thread_self()*
 
@@ -3494,6 +3718,16 @@ uv.get_constrained_memory()                        *uv.get_constrained_memory()*
 
                 Returns: `number`
 
+uv.get_available_memory()                            *uv.get_available_memory()*
+
+                Gets the amount of free memory that is still available to the
+                process (in bytes). This differs from `uv.get_free_memory()`
+                in that it takes into account any limits imposed by the OS. If
+                there is no such constraint, or the constraint is unknown, the
+                amount returned will be identical to `uv.get_free_memory()`.
+
+                Returns: `number`
+
 uv.resident_set_memory()                              *uv.resident_set_memory()*
 
                 Returns the resident set size (RSS) for the current process.
@@ -3558,6 +3792,14 @@ uv.cpu_info()                                                    *uv.cpu_info()*
                     - `idle` : `number`
                     - `irq` : `number`
 
+uv.cpumask_size()                                           *uv.cpumask_size()*
+
+                Returns the maximum size of the mask used for process/thread
+                affinities, or `ENOTSUP` if affinities are not supported on
+                the current platform.
+
+                Returns: `integer` or `fail`
+
 uv.getpid()                                                        *uv.getpid()*
 
                 DEPRECATED: Please use |uv.os_getpid()| instead.
@@ -3614,6 +3856,25 @@ uv.hrtime()                                                        *uv.hrtime()*
 
                 Returns: `number`
 
+uv.clock_gettime({clock_id})                                *uv.clock_gettime()*
+
+                Parameters:
+                - `clock_id`: `string`
+
+                Obtain the current system time from a high-resolution
+                real-time or monotonic clock source. `clock_id` can be the
+                string `"monotonic"` or `"realtime"`.
+
+                The real-time clock counts from the UNIX epoch (1970-01-01)
+                and is subject to time adjustments; it can jump back in time.
+
+                The monotonic clock counts from an arbitrary point in the past
+                and never jumps back in time.
+
+                Returns: `table` or `fail`
+                - `sec`: `integer`
+                - `nsec`: `integer`
+
 uv.uptime()                                                        *uv.uptime()*
 
                 Returns the current system uptime in seconds.
@@ -3752,7 +4013,12 @@ uv.os_setenv({name}, {value})                                   *uv.os_setenv()*
 
                 WARNING: This function is not thread safe.
 
-uv.os_unsetenv()                                              *uv.os_unsetenv()*
+uv.os_unsetenv({name})                                        *uv.os_unsetenv()*
+
+                Parameters:
+                - `name`: `string`
+
+                Unsets the environmental variable specified by `name`.
 
                 Returns: `boolean` or `fail`
 
@@ -3885,14 +4151,28 @@ uv.metrics_idle_time()                                  *uv.metrics_idle_time()*
 
                 Returns: `number`
 
+uv.metrics_info()                                            *uv.metrics_info()*
+
+                Get the metrics table from current set of event loop metrics.
+                It is recommended to retrieve these metrics in a `prepare`
+                callback (see |uv.new_prepare()|, |uv.prepare_start()|) in order
+                to make sure there are no inconsistencies with the metrics
+                counters.
+
+                Returns: `table`
+
+                - `loop_count` : `integer`
+                - `events` : `integer`
+                - `events_waiting` : `integer`
+
 ==============================================================================
 CREDITS                                                            *luv-credits*
 
-This document is a reformatted version of the LUV documentation, based on
-commit c51e705 (5 May 2022) of the luv repository
-https://github.com/luvit/luv/commit/c51e7052ec4f0a25058f70c1b4ee99dd36180e59.
+This document is a reformatted version of the LUV documentation, up-to-date
+with commit dcd1a1c (23 Aug 2023) of the luv repository
+https://github.com/luvit/luv/commit/dcd1a1cad5b05634a7691402d6ca2f214fb4ae76.
 
-Included from https://github.com/nanotee/luv-vimdocs with kind permission.
+Based on https://github.com/nanotee/luv-vimdocs with kind permission.
 
 
 vim:tw=78:ts=8:ft=help:norl: