uv.uv_stream_t
uv_stream_t - Stream handle
[uv_handle_t][] functions also apply.Stream handles provide an abstraction of a duplex communication channel. [uv_stream_t][] is an abstract type, libuv provides 3 stream implementations in the form of [uv_tcp_t][], [uv_pipe_t][] and [uv_tty_t][].
Methods13
function uv_stream_t.shutdown(callback: fun(err: nil | string) -> nil | nil) -> (shutdown uv.uv_shutdown_t | nil, err nil | string, err_name uv.error_name | nil)
Shutdown the outgoing (write) side of a duplex stream. It waits for pending write requests to complete. The callback is called after shutdown is complete.
function uv_stream_t.listen(backlog: integer, callback: fun(err: nil | string) -> nil) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)
Start listening for incoming connections. backlog indicates the number of connections the kernel might queue, same as listen(2). When a new incoming connection is received the callback is called.
function uv_stream_t.accept(client_stream: uv.uv_stream_t) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)
This call is used in conjunction with uv.listen() to accept incoming connections. Call this function after receiving a callback to accept the connection.
When the connection callback is called it is guaranteed that this function will complete successfully the first time. If you attempt to use it more than once, it may fail. It is suggested to only call this function once per connection call. Example
server:listen(128, function (err)
local client = uv.new_tcp()
server:accept(client)
end)
function uv_stream_t.read_start(callback: fun(err: nil | string, data: nil | string) -> nil) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)
Read data from an incoming stream. The callback will be made several times until there is no more data to read or uv.read_stop() is called. When we've reached EOF, data will be nil. Example
stream:read_start(function (err, chunk)
if err then
-- handle read error
elseif chunk then
-- handle data
else
-- handle disconnect
end
end)
function uv_stream_t.read_stop() -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)
Stop reading data from the stream. The read callback will no longer be called.
This function is idempotent and may be safely called on a stopped stream.
function uv_stream_t.write(data: uv.buffer, callback: fun(err: nil | string) -> nil | nil) -> (write uv.uv_write_t | nil, err nil | string, err_name uv.error_name | nil)
Write data to stream.
data can either be a Lua string or a table of strings. If a table is passed in, the C backend will use writev to send all strings in a single system call.
The optional callback is for knowing when the write is complete.
function uv_stream_t.write2(data: uv.buffer, send_handle: uv.uv_stream_t, callback: fun(err: nil | string) -> nil | nil) -> (write uv.uv_write_t | nil, err nil | string, err_name uv.error_name | nil)
Extended write function for sending handles over a pipe. The pipe must be initialized with ipc option true. Note: send_handle must be a TCP socket or pipe, which is a server or a connection (listening or connected state). Bound sockets or pipes will be assumed to be servers.
function uv_stream_t.try_write(data: uv.buffer) -> (bytes_written nil | integer, err nil | string, err_name uv.error_name | nil)
Same as uv.write(), but won't queue a write request if it can't be completed immediately.
Will return number of bytes written (can be less than the supplied buffer size).
function uv_stream_t.try_write2(data: uv.buffer, send_handle: uv.uv_stream_t) -> (bytes_written nil | integer, err nil | string, err_name uv.error_name | nil)
Like uv.write2(), but with the properties of uv.try_write(). Not supported on Windows, where it returns UV_EAGAIN.
Will return number of bytes written (can be less than the supplied buffer size).
function uv_stream_t.is_readable() -> boolean
Returns true if the stream is readable, false otherwise.
function uv_stream_t.is_writable() -> boolean
Returns true if the stream is writable, false otherwise.
function uv_stream_t.set_blocking(blocking: boolean) -> (success 0 | nil, err nil | string, err_name uv.error_name | nil)
Enable or disable blocking mode for a stream.
When blocking mode is enabled all writes complete synchronously. The interface remains unchanged otherwise, e.g. completion or failure of the operation will still be reported through a callback which is made asynchronously. Warning: Relying too much on this API is not recommended. It is likely to change significantly in the future. Currently this only works on Windows and only for uv_pipe_t handles. Also libuv currently makes no ordering guarantee when the blocking mode is changed after write requests have already been submitted. Therefore it is recommended to set the blocking mode immediately after opening or creating the stream.
function uv_stream_t.get_write_queue_size() -> integer
Returns the stream's write queue size.