1 2.. _stream: 3 4:c:type:`uv_stream_t` --- Stream handle 5======================================= 6 7Stream handles provide an abstraction of a duplex communication channel. 8:c:type:`uv_stream_t` is an abstract type, libuv provides 3 stream implementations 9in the form of :c:type:`uv_tcp_t`, :c:type:`uv_pipe_t` and :c:type:`uv_tty_t`. 10 11 12Data types 13---------- 14 15.. c:type:: uv_stream_t 16 17 Stream handle type. 18 19.. c:type:: uv_connect_t 20 21 Connect request type. 22 23.. c:type:: uv_shutdown_t 24 25 Shutdown request type. 26 27.. c:type:: uv_write_t 28 29 Write request type. Careful attention must be paid when reusing objects of 30 this type. When a stream is in non-blocking mode, write requests sent 31 with ``uv_write`` will be queued. Reusing objects at this point is undefined 32 behaviour. It is safe to reuse the ``uv_write_t`` object only after the 33 callback passed to ``uv_write`` is fired. 34 35.. c:type:: void (*uv_read_cb)(uv_stream_t* stream, ssize_t nread, const uv_buf_t* buf) 36 37 Callback called when data was read on a stream. 38 39 `nread` is > 0 if there is data available or < 0 on error. When we've 40 reached EOF, `nread` will be set to ``UV_EOF``. When `nread` < 0, 41 the `buf` parameter might not point to a valid buffer; in that case 42 `buf.len` and `buf.base` are both set to 0. 43 44 .. note:: 45 `nread` might be 0, which does *not* indicate an error or EOF. This 46 is equivalent to ``EAGAIN`` or ``EWOULDBLOCK`` under ``read(2)``. 47 48 The callee is responsible for stopping/closing the stream when an error happens 49 by calling :c:func:`uv_read_stop` or :c:func:`uv_close`. Trying to read 50 from the stream again is undefined. 51 52 The callee is responsible for freeing the buffer, libuv does not reuse it. 53 The buffer may be a null buffer (where `buf->base` == NULL and `buf->len` == 0) 54 on error. 55 56.. c:type:: void (*uv_write_cb)(uv_write_t* req, int status) 57 58 Callback called after data was written on a stream. `status` will be 0 in 59 case of success, < 0 otherwise. 60 61.. c:type:: void (*uv_connect_cb)(uv_connect_t* req, int status) 62 63 Callback called after a connection started by :c:func:`uv_connect` is done. 64 `status` will be 0 in case of success, < 0 otherwise. 65 66.. c:type:: void (*uv_shutdown_cb)(uv_shutdown_t* req, int status) 67 68 Callback called after a shutdown request has been completed. `status` will 69 be 0 in case of success, < 0 otherwise. 70 71.. c:type:: void (*uv_connection_cb)(uv_stream_t* server, int status) 72 73 Callback called when a stream server has received an incoming connection. 74 The user can accept the connection by calling :c:func:`uv_accept`. 75 `status` will be 0 in case of success, < 0 otherwise. 76 77 78Public members 79^^^^^^^^^^^^^^ 80 81.. c:member:: size_t uv_stream_t.write_queue_size 82 83 Contains the amount of queued bytes waiting to be sent. Readonly. 84 85.. c:member:: uv_stream_t* uv_connect_t.handle 86 87 Pointer to the stream where this connection request is running. 88 89.. c:member:: uv_stream_t* uv_shutdown_t.handle 90 91 Pointer to the stream where this shutdown request is running. 92 93.. c:member:: uv_stream_t* uv_write_t.handle 94 95 Pointer to the stream where this write request is running. 96 97.. c:member:: uv_stream_t* uv_write_t.send_handle 98 99 Pointer to the stream being sent using this write request. 100 101.. seealso:: The :c:type:`uv_handle_t` members also apply. 102 103 104API 105--- 106 107.. c:function:: int uv_shutdown(uv_shutdown_t* req, uv_stream_t* handle, uv_shutdown_cb cb) 108 109 Shutdown the outgoing (write) side of a duplex stream. It waits for pending 110 write requests to complete. The `handle` should refer to a initialized stream. 111 `req` should be an uninitialized shutdown request struct. The `cb` is called 112 after shutdown is complete. 113 114.. c:function:: int uv_listen(uv_stream_t* stream, int backlog, uv_connection_cb cb) 115 116 Start listening for incoming connections. `backlog` indicates the number of 117 connections the kernel might queue, same as :man:`listen(2)`. When a new 118 incoming connection is received the :c:type:`uv_connection_cb` callback is 119 called. 120 121.. c:function:: int uv_accept(uv_stream_t* server, uv_stream_t* client) 122 123 This call is used in conjunction with :c:func:`uv_listen` to accept incoming 124 connections. Call this function after receiving a :c:type:`uv_connection_cb` 125 to accept the connection. Before calling this function the client handle must 126 be initialized. < 0 return value indicates an error. 127 128 When the :c:type:`uv_connection_cb` callback is called it is guaranteed that 129 this function will complete successfully the first time. If you attempt to use 130 it more than once, it may fail. It is suggested to only call this function once 131 per :c:type:`uv_connection_cb` call. 132 133 .. note:: 134 `server` and `client` must be handles running on the same loop. 135 136.. c:function:: int uv_read_start(uv_stream_t* stream, uv_alloc_cb alloc_cb, uv_read_cb read_cb) 137 138 Read data from an incoming stream. The :c:type:`uv_read_cb` callback will 139 be made several times until there is no more data to read or 140 :c:func:`uv_read_stop` is called. 141 142 .. versionchanged:: 1.38.0 :c:func:`uv_read_start()` now consistently 143 returns `UV_EALREADY` when called twice, and `UV_EINVAL` when the 144 stream is closing. With older libuv versions, it returns `UV_EALREADY` 145 on Windows but not UNIX, and `UV_EINVAL` on UNIX but not Windows. 146 147.. c:function:: int uv_read_stop(uv_stream_t*) 148 149 Stop reading data from the stream. The :c:type:`uv_read_cb` callback will 150 no longer be called. 151 152 This function is idempotent and may be safely called on a stopped stream. 153 154 This function will always succeed; hence, checking its return value is 155 unnecessary. A non-zero return indicates that finishing releasing resources 156 may be pending on the next input event on that TTY on Windows, and does not 157 indicate failure. 158 159.. c:function:: int uv_write(uv_write_t* req, uv_stream_t* handle, const uv_buf_t bufs[], unsigned int nbufs, uv_write_cb cb) 160 161 Write data to stream. Buffers are written in order. Example: 162 163 :: 164 165 void cb(uv_write_t* req, int status) { 166 /* Logic which handles the write result */ 167 } 168 169 uv_buf_t a[] = { 170 { .base = "1", .len = 1 }, 171 { .base = "2", .len = 1 } 172 }; 173 174 uv_buf_t b[] = { 175 { .base = "3", .len = 1 }, 176 { .base = "4", .len = 1 } 177 }; 178 179 uv_write_t req1; 180 uv_write_t req2; 181 182 /* writes "1234" */ 183 uv_write(&req1, stream, a, 2, cb); 184 uv_write(&req2, stream, b, 2, cb); 185 186 .. note:: 187 The memory pointed to by the buffers must remain valid until the callback gets called. 188 This also holds for :c:func:`uv_write2`. 189 190.. c:function:: int uv_write2(uv_write_t* req, uv_stream_t* handle, const uv_buf_t bufs[], unsigned int nbufs, uv_stream_t* send_handle, uv_write_cb cb) 191 192 Extended write function for sending handles over a pipe. The pipe must be 193 initialized with `ipc` == 1. 194 195 .. note:: 196 `send_handle` must be a TCP, pipe and UDP handle on Unix, or a TCP 197 handle on Windows, which is a server or a connection (listening or 198 connected state). Bound sockets or pipes will be assumed to be servers. 199 200.. c:function:: int uv_try_write(uv_stream_t* handle, const uv_buf_t bufs[], unsigned int nbufs) 201 202 Same as :c:func:`uv_write`, but won't queue a write request if it can't be 203 completed immediately. 204 205 Will return either: 206 207 * > 0: number of bytes written (can be less than the supplied buffer size). 208 * < 0: negative error code (``UV_EAGAIN`` is returned if no data can be sent 209 immediately). 210 211.. c:function:: int uv_try_write2(uv_stream_t* handle, const uv_buf_t bufs[], unsigned int nbufs, uv_stream_t* send_handle) 212 213 Same as :c:func:`uv_try_write` and extended write function for sending 214 handles over a pipe like c:func:`uv_write2`. 215 216 Try to send a handle is not supported on Windows, 217 where it returns ``UV_EAGAIN``. 218 219 .. versionadded:: 1.42.0 220 221.. c:function:: int uv_is_readable(const uv_stream_t* handle) 222 223 Returns 1 if the stream is readable, 0 otherwise. 224 225.. c:function:: int uv_is_writable(const uv_stream_t* handle) 226 227 Returns 1 if the stream is writable, 0 otherwise. 228 229.. c:function:: int uv_stream_set_blocking(uv_stream_t* handle, int blocking) 230 231 Enable or disable blocking mode for a stream. 232 233 When blocking mode is enabled all writes complete synchronously. The 234 interface remains unchanged otherwise, e.g. completion or failure of the 235 operation will still be reported through a callback which is made 236 asynchronously. 237 238 .. warning:: 239 Relying too much on this API is not recommended. It is likely to change 240 significantly in the future. 241 242 Currently only works on Windows for :c:type:`uv_pipe_t` handles. 243 On UNIX platforms, all :c:type:`uv_stream_t` handles are supported. 244 245 Also libuv currently makes no ordering guarantee when the blocking mode 246 is changed after write requests have already been submitted. Therefore it is 247 recommended to set the blocking mode immediately after opening or creating 248 the stream. 249 250 .. versionchanged:: 1.4.0 UNIX implementation added. 251 252.. c:function:: size_t uv_stream_get_write_queue_size(const uv_stream_t* stream) 253 254 Returns `stream->write_queue_size`. 255 256 .. versionadded:: 1.19.0 257 258.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 259
