|
160
|
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.
|
