diff options
Diffstat (limited to 'runtime/doc/luvref.txt')
| -rw-r--r-- | runtime/doc/luvref.txt | 3898 |
1 files changed, 3898 insertions, 0 deletions
diff --git a/runtime/doc/luvref.txt b/runtime/doc/luvref.txt new file mode 100644 index 0000000000..ee45444b42 --- /dev/null +++ b/runtime/doc/luvref.txt @@ -0,0 +1,3898 @@ +*luvref.txt* Nvim + + + LUV REFERENCE MANUAL + + +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()`). + +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: + + > + local uv = vim.loop + + 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 one +non-function field exists: `uv.constants`, which is a table. + +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` + +============================================================================== +CONTENTS *luv-contents* + +This documentation is mostly a retelling of the libuv API documentation +(http://docs.libuv.org/en/v1.x/api.html) within the context of luv's Lua API. +Low-level implementation details and unexposed C functions and types are not +documented here except for when they are relevant to behavior seen in the Lua +module. + +- |luv-error-handling| — Error handling +- |luv-version-checking| — Version checking +- |uv_loop_t| — Event loop +- |uv_req_t| — Base request +- |uv_handle_t| — Base handle + - |uv_timer_t| — Timer handle + - |uv_prepare_t| — Prepare handle + - |uv_check_t| — Check handle + - |uv_idle_t| — Idle handle + - |uv_async_t| — Async handle + - |uv_poll_t| — Poll handle + - |uv_signal_t| — Signal handle + - |uv_process_t| — Process handle + - |uv_stream_t| — Stream handle + - |uv_tcp_t| — TCP handle + - |uv_pipe_t| — Pipe handle + - |uv_tty_t| — TTY handle + - |uv_udp_t| — UDP handle + - |uv_fs_event_t| — FS Event handle + - |uv_fs_poll_t| — FS Poll handle +- |luv-file-system-operations| — File system operations +- |luv-thread-pool-work-scheduling| — Thread pool work scheduling +- |luv-dns-utility-functions| — DNS utility functions +- |luv-threading-and-synchronization-utilities| — Threading and + synchronization utilities +- |luv-miscellaneous-utilities| — Miscellaneous utilities +- |luv-metrics-operations| — Metrics operations + +============================================================================== +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. + +- `nil` idiomatically indicates failure +- `err` is a string with the format `{name}: {message}` + - `{name}` is the error name provided internally by `uv_err_name` + - `{message}` is a human-readable message provided internally by + `uv_strerror` +- `name` is the same string used to construct `err` + +This tuple is referred to below as the `fail` pseudo-type. + +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. + +============================================================================== +VERSION CHECKING *luv-version-checking* + +uv.version() *uv.version()* + + Returns the libuv version packed into a single integer. 8 bits + are used for each component, with the patch number stored in + the 8 least significant bits. For example, this would be + 0x010203 in libuv 1.2.3. + + Returns: `integer` + +uv.version_string() *uv.version_string()* + + Returns the libuv version number as a string. For example, + this would be "1.2.3" in libuv 1.2.3. For non-release + versions, the version suffix is included. + + Returns: `string` + +============================================================================== +`uv_loop_t` — Event loop *luv-event-loop* *uv_loop_t* + +The event loop is the central part of libuv's functionality. It takes care of +polling for I/O and scheduling callbacks to be run based on different sources +of events. + +In luv, there is an implicit uv loop for every Lua state that loads the +library. You can use this library in an multi-threaded environment as long as +each thread has it's own Lua state with its corresponding own uv loop. This +loop is not directly exposed to users in the Lua module. + +uv.loop_close() *uv.loop_close()* + + Closes all internal loop resources. In normal execution, the + loop will automatically be closed when it is garbage collected + by Lua, so it is not necessary to explicitly call + `loop_close()`. Call this function only after the loop has + finished executing and all open handles and requests have been + closed, or it will return `EBUSY`. + + Returns: `0` or `fail` + +uv.run([{mode}]) *uv.run()* + + Parameters: + - `mode`: `string` or `nil` (default: `"default"`) + + This function runs the event loop. It will act differently + depending on the specified mode: + + - `"default"`: Runs the event loop until there are no more + active and referenced handles or requests. Returns `true` + if |uv.stop()| was called and there are still active + handles or requests. Returns `false` in all other cases. + + - `"once"`: Poll for I/O once. Note that this function + blocks if there are no pending callbacks. Returns `false` + when done (no active handles or requests left), or `true` + if more callbacks are expected (meaning you should run the + event loop again sometime in the future). + + - `"nowait"`: Poll for I/O once but don't block if there are + no pending callbacks. Returns `false` if done (no active + handles or requests left), or `true` if more callbacks are + expected (meaning you should run the event loop again + sometime in the future). + + Returns: `boolean` or `fail` + + Note: Luvit will implicitly call `uv.run()` after loading user + code, but if you use the luv bindings directly, you need to + call this after registering your initial set of event + callbacks to start the event loop. + +uv.loop_configure({option}, {...}) *uv.loop_configure()* + + Parameters: + - `option`: `string` + - `...`: depends on `option`, see below + + Set additional loop options. You should normally call this + before the first call to uv_run() unless mentioned otherwise. + + Supported options: + + - `"block_signal"`: Block a signal when polling for new + events. The second argument to loop_configure() is the + signal name (as a lowercase string) or the signal number. + This operation is currently only implemented for + `"sigprof"` signals, to suppress unnecessary wakeups when + using a sampling profiler. Requesting other signals will + fail with `EINVAL`. + - `"metrics_idle_time"`: Accumulate the amount of idle time + the event loop spends in the event provider. This option + is necessary to use `metrics_idle_time()`. + + An example of a valid call to this function is: + + > + uv.loop_configure("block_signal", "sigprof") +< + + Returns: `0` or `fail` + + Note: Be prepared to handle the `ENOSYS` error; it means the + loop option is not supported by the platform. + +uv.loop_mode() *uv.loop_mode()* + + If the loop is running, returns a string indicating the mode + in use. If the loop is not running, `nil` is returned instead. + + Returns: `string` or `nil` + +uv.loop_alive() *uv.loop_alive()* + + Returns `true` if there are referenced active handles, active + requests, or closing handles in the loop; otherwise, `false`. + + Returns: `boolean` or `fail` + +uv.stop() *uv.stop()* + + Stop the event loop, causing |uv.run()| to end as soon as + possible. This will happen not sooner than the next loop + iteration. If this function was called before blocking for + I/O, the loop won't block for I/O on this iteration. + + Returns: Nothing. + +uv.backend_fd() *uv.backend_fd()* + + Get backend file descriptor. Only kqueue, epoll, and event + ports are supported. + + This can be used in conjunction with `uv.run("nowait")` to + poll in one thread and run the event loop's callbacks in + another + + Returns: `integer` or `nil` + + Note: Embedding a kqueue fd in another kqueue pollset doesn't + work on all platforms. It's not an error to add the fd but it + never generates events. + +uv.backend_timeout() *uv.backend_timeout()* + + Get the poll timeout. The return value is in milliseconds, or + -1 for no timeout. + + Returns: `integer` + +uv.now() *uv.now()* + + Returns the current timestamp in milliseconds. The timestamp + is cached at the start of the event loop tick, see + |uv.update_time()| for details and rationale. + + The timestamp increases monotonically from some arbitrary + point in time. Don't make assumptions about the starting + point, you will only get disappointed. + + Returns: `integer` + + Note: Use |uv.hrtime()| if you need sub-millisecond + granularity. + +uv.update_time() *uv.update_time()* + + Update the event loop's concept of "now". Libuv caches the + current time at the start of the event loop tick in order to + reduce the number of time-related system calls. + + You won't normally need to call this function unless you have + callbacks that block the event loop for longer periods of + time, where "longer" is somewhat subjective but probably on + the order of a millisecond or more. + + Returns: Nothing. + +uv.walk({callback}) *uv.walk()* + + Parameters: + - `callback`: `callable` + - `handle`: `userdata` for sub-type of |uv_handle_t| + + Walk the list of handles: `callback` will be executed with + each handle. + + Returns: Nothing. + + > + -- Example usage of uv.walk to close all handles that + -- aren't already closing. + uv.walk(function (handle) + if not handle:is_closing() then + handle:close() + end + end) +< + +============================================================================== +`uv_req_t` — Base request *luv-base-request* *uv_req_t* + +`uv_req_t` is the base type for all libuv request types. + +uv.cancel({req}) *uv.cancel()* + + > method form `req:cancel()` + + Parameters: + - `req`: `userdata` for sub-type of |uv_req_t| + + Cancel a pending request. Fails if the request is executing or + has finished executing. Only cancellation of |uv_fs_t|, + `uv_getaddrinfo_t`, `uv_getnameinfo_t` and `uv_work_t` + requests is currently supported. + + Returns: `0` or `fail` + +uv.req_get_type({req}) *uv.req_get_type()* + + > method form `req:get_type()` + + Parameters: + - `req`: `userdata` for sub-type of |uv_req_t| + + Returns the name of the struct for a given request (e.g. + `"fs"` for |uv_fs_t|) and the libuv enum integer for the + request's type (`uv_req_type`). + + Returns: `string, integer` + +============================================================================== +`uv_handle_t` — Base handle *luv-base-handle* *uv_handle_t* + +`uv_handle_t` is the base type for all libuv handle types. All API functions +defined here work with any handle type. + +uv.is_active({handle}) *uv.is_active()* + + > method form `handle:is_active()` + + Parameters: + - `handle`: `userdata` for sub-type of |uv_handle_t| + + Returns `true` if the handle is active, `false` 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()|, + |uv.timer_start()| etc. until it has been stopped with a + call to its respective stop function. + + Returns: `boolean` or `fail` + +uv.is_closing({handle}) *uv.is_closing()* + + > method form `handle:is_closing()` + + Parameters: + - `handle`: `userdata` for sub-type of |uv_handle_t| + + Returns `true` if the handle is closing or closed, `false` + otherwise. + + Returns: `boolean` or `fail` + + Note: This function should only be used between the + initialization of the handle and the arrival of the close + callback. + +uv.close({handle} [, {callback}]) *uv.close()* + + > method form `handle:close([callback])` + + Parameters: + - `handle`: `userdata` for sub-type of |uv_handle_t| + - `callback`: `callable` or `nil` + + Request handle to be closed. `callback` 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 + `callback` 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 + `ECANCELED`. + + Returns: Nothing. + +uv.ref({handle}) *uv.ref()* + + > method form `handle:ref()` + + Parameters: + - `handle`: `userdata` for sub-type of |uv_handle_t| + + Reference the given handle. References are idempotent, that + is, if a handle is already referenced calling this function + again will have no effect. + + Returns: Nothing. + + See |luv-reference-counting|. + +uv.unref({handle}) *uv.unref()* + + > method form `handle:unref()` + + Parameters: + - `handle`: `userdata` for sub-type of |uv_handle_t| + + Un-reference the given handle. References are idempotent, that + is, if a handle is not referenced calling this function again + will have no effect. + + Returns: Nothing. + +See |luv-reference-counting|. + +uv.has_ref({handle}) *uv.has_ref()* + + > method form `handle:has_ref()` + + Parameters: + - `handle`: `userdata` for sub-type of |uv_handle_t| + + Returns `true` if the handle referenced, `false` if not. + + Returns: `boolean` or `fail` + + See |luv-reference-counting|. + +uv.send_buffer_size({handle} [, {size}]) *uv.send_buffer_size()* + + > method form `handle:send_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 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. + +Timer handles are used to schedule callbacks to be called in the future. + +uv.new_timer() *uv.new_timer()* + + Creates and initializes a new |uv_timer_t|. Returns the Lua + userdata wrapping it. + + Returns: `uv_timer_t userdata` or `fail` + + > + -- Creating a simple setTimeout wrapper + local function setTimeout(timeout, callback) + local timer = uv.new_timer() + timer:start(timeout, 0, function () + timer:stop() + timer:close() + callback() + end) + return timer + end + + -- Creating a simple setInterval wrapper + local function setInterval(interval, callback) + local timer = uv.new_timer() + timer:start(interval, interval, function () + callback() + end) + return timer + end + + -- And clearInterval + local function clearInterval(timer) + timer:stop() + timer:close() + end +< + +uv.timer_start({timer}, {timeout}, {repeat}, {callback}) *uv.timer_start()* + + > method form `timer:start(timeout, repeat, callback)` + + Parameters: + - `timer`: `uv_timer_t userdata` + - `timeout`: `integer` + - `repeat`: `integer` + - `callback`: `callable` + + Start the timer. `timeout` and `repeat` are in milliseconds. + + If `timeout` is zero, the callback fires on the next event + loop iteration. If `repeat` is non-zero, the callback fires + first after `timeout` milliseconds and then repeatedly after + `repeat` milliseconds. + + Returns: `0` or `fail` + +uv.timer_stop({timer}) *uv.timer_stop()* + + > method form `timer:stop()` + + Parameters: + - `timer`: `uv_timer_t userdata` + + Stop the timer, the callback will not be called anymore. + + Returns: `0` or `fail` + +uv.timer_again({timer}) *uv.timer_again()* + + > method form `timer:again()` + + Parameters: + - `timer`: `uv_timer_t userdata` + + Stop the timer, and if it is repeating restart it using the + repeat value as the timeout. If the timer has never been + started before it raises `EINVAL`. + + Returns: `0` or `fail` + +uv.timer_set_repeat({timer}, {repeat}) *uv.timer_set_repeat()* + + > method form `timer:set_repeat(repeat)` + + Parameters: + - `timer`: `uv_timer_t userdata` + - `repeat`: `integer` + + Set the repeat interval value in milliseconds. The timer will + be scheduled to run on the given interval, regardless of the + callback execution duration, and will follow normal timer + semantics in the case of a time-slice overrun. + + For example, if a 50 ms repeating timer first runs for 17 ms, + it will be scheduled to run again 33 ms later. If other tasks + consume more than the 33 ms following the first timer + callback, then the callback will run as soon as possible. + + Returns: Nothing. + +uv.timer_get_repeat({timer}) *uv.timer_get_repeat()* + + > method form `timer:get_repeat()` + + Parameters: + - `timer`: `uv_timer_t userdata` + + Get the timer repeat value. + + Returns: `integer` + +uv.timer_get_due_in({timer}) *uv.timer_get_due_in()* + + > method form `timer:get_due_in()` + + Parameters: + - `timer`: `uv_timer_t userdata` + + Get the timer due value or 0 if it has expired. The time is + relative to |uv.now()|. + + Returns: `integer` + + Note: New in libuv version 1.40.0. + +============================================================================== +`uv_prepare_t` — Prepare handle *luv-prepare-handle* *uv_prepare_t* + +> |uv_handle_t| functions also apply. + +Prepare handles will run the given callback once per loop iteration, right +before polling for I/O. + + > + local prepare = uv.new_prepare() + prepare:start(function() + print("Before I/O polling") + end) +< + +uv.new_prepare() *uv.new_prepare()* + + Creates and initializes a new |uv_prepare_t|. Returns the Lua + userdata wrapping it. + + Returns: `uv_prepare_t userdata` or `fail` + +uv.prepare_start({prepare}, {callback}) *uv.prepare_start()* + + > method form `prepare:start(callback)` + + Parameters: + - `prepare`: `uv_prepare_t userdata` + - `callback`: `callable` + + Start the handle with the given callback. + + Returns: `0` or `fail` + +uv.prepare_stop({prepare}) *uv.prepare_stop()* + + > method form `prepare:stop()` + + Parameters: + - `prepare`: `uv_prepare_t userdata` + + Stop the handle, the callback will no longer be called. + + Returns: `0` or `fail` + +============================================================================== +`uv_check_t` — Check handle *luv-check-handle* *uv_check_t* + +> |uv_handle_t| functions also apply. + +Check handles will run the given callback once per loop iteration, right after +polling for I/O. + + > + local check = uv.new_check() + check:start(function() + print("After I/O polling") + end) +< + +uv.new_check() *uv.new_check()* + + Creates and initializes a new |uv_check_t|. Returns the Lua + userdata wrapping it. + + Returns: `uv_check_t userdata` or `fail` + +uv.check_start({check}, {callback}) *uv.check_start()* + + > method form `check:start(callback)` + + Parameters: + - `check`: `uv_check_t userdata` + - `callback`: `callable` + + Start the handle with the given callback. + + Returns: `0` or `fail` + +uv.check_stop({check}) *uv.check_stop()* + + > method form `check:stop()` + + Parameters: + - `check`: `uv_check_t userdata` + + Stop the handle, the callback will no longer be called. + + Returns: `0` or `fail` + +============================================================================== +`uv_idle_t` — Idle handle *luv-idle-handle* *uv_idle_t* + +> |uv_handle_t| functions also apply. + +Idle handles will run the given callback once per loop iteration, right before +the |uv_prepare_t| handles. + +Note: The notable difference with prepare handles is that when there are +active idle handles, the loop will perform a zero timeout poll instead of +blocking for I/O. + +WARNING: Despite the name, idle handles will get their callbacks called on +every loop iteration, not when the loop is actually "idle". + + > + local idle = uv.new_idle() + idle:start(function() + print("Before I/O polling, no blocking") + end) +< + +uv.new_idle() *uv.new_idle()* + + Creates and initializes a new |uv_idle_t|. Returns the Lua + userdata wrapping it. + + Returns: `uv_idle_t userdata` or `fail` + +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. + + > + 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` or `nil` + - `...`: `threadargs` passed to/from + `uv.async_send(async, ...)` + + Creates and initializes a new |uv_async_t|. Returns the Lua + userdata wrapping it. A `nil` callback is allowed. + + 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) +(http://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 the handle to report an error, but it might +also start polling another socket. However the fd can be safely closed +immediately after a call to |uv.poll_stop()| or |uv.close()|. + +Note: On windows only sockets can be polled with poll handles. On Unix any +file descriptor that would be accepted by poll(2) can be used. + +uv.new_poll({fd}) *uv.new_poll()* |