Mercurial

comparison third_party/libuv/docs/src/stream.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
1
2 .. _stream:
3
4 :c:type:`uv_stream_t` --- Stream handle
5 =======================================
6
7 Stream handles provide an abstraction of a duplex communication channel.
8 :c:type:`uv_stream_t` is an abstract type, libuv provides 3 stream implementations
9 in the form of :c:type:`uv_tcp_t`, :c:type:`uv_pipe_t` and :c:type:`uv_tty_t`.
10
11
12 Data 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
78 Public 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
104 API
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.