]>
Commit | Line | Data |
---|---|---|
666a3af9 DB |
1 | /* |
2 | * QEMU I/O channels | |
3 | * | |
4 | * Copyright (c) 2015 Red Hat, Inc. | |
5 | * | |
6 | * This library is free software; you can redistribute it and/or | |
7 | * modify it under the terms of the GNU Lesser General Public | |
8 | * License as published by the Free Software Foundation; either | |
c8198bd5 | 9 | * version 2.1 of the License, or (at your option) any later version. |
666a3af9 DB |
10 | * |
11 | * This library is distributed in the hope that it will be useful, | |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 | * Lesser General Public License for more details. | |
15 | * | |
16 | * You should have received a copy of the GNU Lesser General Public | |
17 | * License along with this library; if not, see <http://www.gnu.org/licenses/>. | |
18 | * | |
19 | */ | |
20 | ||
2a6a4076 MA |
21 | #ifndef QIO_CHANNEL_H |
22 | #define QIO_CHANNEL_H | |
666a3af9 | 23 | |
666a3af9 | 24 | #include "qom/object.h" |
c4c497d2 | 25 | #include "qemu/coroutine.h" |
bf88c124 | 26 | #include "block/aio.h" |
666a3af9 DB |
27 | |
28 | #define TYPE_QIO_CHANNEL "qio-channel" | |
c821774a | 29 | OBJECT_DECLARE_TYPE(QIOChannel, QIOChannelClass, |
30b5707c | 30 | QIO_CHANNEL) |
666a3af9 | 31 | |
666a3af9 DB |
32 | |
33 | #define QIO_CHANNEL_ERR_BLOCK -2 | |
34 | ||
b88651cb LB |
35 | #define QIO_CHANNEL_WRITE_FLAG_ZERO_COPY 0x1 |
36 | ||
666a3af9 DB |
37 | typedef enum QIOChannelFeature QIOChannelFeature; |
38 | ||
39 | enum QIOChannelFeature { | |
8fbf6612 FF |
40 | QIO_CHANNEL_FEATURE_FD_PASS, |
41 | QIO_CHANNEL_FEATURE_SHUTDOWN, | |
42 | QIO_CHANNEL_FEATURE_LISTEN, | |
b88651cb | 43 | QIO_CHANNEL_FEATURE_WRITE_ZERO_COPY, |
666a3af9 DB |
44 | }; |
45 | ||
46 | ||
47 | typedef enum QIOChannelShutdown QIOChannelShutdown; | |
48 | ||
49 | enum QIOChannelShutdown { | |
a2458b6f DB |
50 | QIO_CHANNEL_SHUTDOWN_READ = 1, |
51 | QIO_CHANNEL_SHUTDOWN_WRITE = 2, | |
52 | QIO_CHANNEL_SHUTDOWN_BOTH = 3, | |
666a3af9 DB |
53 | }; |
54 | ||
55 | typedef gboolean (*QIOChannelFunc)(QIOChannel *ioc, | |
56 | GIOCondition condition, | |
57 | gpointer data); | |
58 | ||
59 | /** | |
60 | * QIOChannel: | |
61 | * | |
62 | * The QIOChannel defines the core API for a generic I/O channel | |
63 | * class hierarchy. It is inspired by GIOChannel, but has the | |
64 | * following differences | |
65 | * | |
66 | * - Use QOM to properly support arbitrary subclassing | |
67 | * - Support use of iovecs for efficient I/O with multiple blocks | |
68 | * - None of the character set translation, binary data exclusively | |
69 | * - Direct support for QEMU Error object reporting | |
70 | * - File descriptor passing | |
71 | * | |
72 | * This base class is abstract so cannot be instantiated. There | |
73 | * will be subclasses for dealing with sockets, files, and higher | |
74 | * level protocols such as TLS, WebSocket, etc. | |
75 | */ | |
76 | ||
77 | struct QIOChannel { | |
78 | Object parent; | |
79 | unsigned int features; /* bitmask of QIOChannelFeatures */ | |
20f4aa26 | 80 | char *name; |
c4c497d2 PB |
81 | AioContext *ctx; |
82 | Coroutine *read_coroutine; | |
83 | Coroutine *write_coroutine; | |
a5897205 PB |
84 | #ifdef _WIN32 |
85 | HANDLE event; /* For use with GSource on Win32 */ | |
86 | #endif | |
666a3af9 DB |
87 | }; |
88 | ||
89 | /** | |
90 | * QIOChannelClass: | |
91 | * | |
92 | * This class defines the contract that all subclasses | |
93 | * must follow to provide specific channel implementations. | |
94 | * The first five callbacks are mandatory to support, others | |
95 | * provide additional optional features. | |
96 | * | |
97 | * Consult the corresponding public API docs for a description | |
8659f317 LS |
98 | * of the semantics of each callback. io_shutdown in particular |
99 | * must be thread-safe, terminate quickly and must not block. | |
666a3af9 DB |
100 | */ |
101 | struct QIOChannelClass { | |
102 | ObjectClass parent; | |
103 | ||
104 | /* Mandatory callbacks */ | |
105 | ssize_t (*io_writev)(QIOChannel *ioc, | |
106 | const struct iovec *iov, | |
107 | size_t niov, | |
108 | int *fds, | |
109 | size_t nfds, | |
b88651cb | 110 | int flags, |
666a3af9 DB |
111 | Error **errp); |
112 | ssize_t (*io_readv)(QIOChannel *ioc, | |
113 | const struct iovec *iov, | |
114 | size_t niov, | |
115 | int **fds, | |
116 | size_t *nfds, | |
117 | Error **errp); | |
118 | int (*io_close)(QIOChannel *ioc, | |
119 | Error **errp); | |
120 | GSource * (*io_create_watch)(QIOChannel *ioc, | |
121 | GIOCondition condition); | |
122 | int (*io_set_blocking)(QIOChannel *ioc, | |
123 | bool enabled, | |
124 | Error **errp); | |
125 | ||
126 | /* Optional callbacks */ | |
127 | int (*io_shutdown)(QIOChannel *ioc, | |
128 | QIOChannelShutdown how, | |
129 | Error **errp); | |
130 | void (*io_set_cork)(QIOChannel *ioc, | |
131 | bool enabled); | |
132 | void (*io_set_delay)(QIOChannel *ioc, | |
133 | bool enabled); | |
134 | off_t (*io_seek)(QIOChannel *ioc, | |
135 | off_t offset, | |
136 | int whence, | |
137 | Error **errp); | |
bf88c124 PB |
138 | void (*io_set_aio_fd_handler)(QIOChannel *ioc, |
139 | AioContext *ctx, | |
140 | IOHandler *io_read, | |
141 | IOHandler *io_write, | |
142 | void *opaque); | |
b88651cb LB |
143 | int (*io_flush)(QIOChannel *ioc, |
144 | Error **errp); | |
666a3af9 DB |
145 | }; |
146 | ||
147 | /* General I/O handling functions */ | |
148 | ||
149 | /** | |
150 | * qio_channel_has_feature: | |
151 | * @ioc: the channel object | |
152 | * @feature: the feature to check support of | |
153 | * | |
154 | * Determine whether the channel implementation supports | |
155 | * the optional feature named in @feature. | |
156 | * | |
157 | * Returns: true if supported, false otherwise. | |
158 | */ | |
159 | bool qio_channel_has_feature(QIOChannel *ioc, | |
160 | QIOChannelFeature feature); | |
161 | ||
d8d3c7cc FF |
162 | /** |
163 | * qio_channel_set_feature: | |
164 | * @ioc: the channel object | |
165 | * @feature: the feature to set support for | |
166 | * | |
167 | * Add channel support for the feature named in @feature. | |
168 | */ | |
169 | void qio_channel_set_feature(QIOChannel *ioc, | |
170 | QIOChannelFeature feature); | |
171 | ||
20f4aa26 DB |
172 | /** |
173 | * qio_channel_set_name: | |
174 | * @ioc: the channel object | |
175 | * @name: the name of the channel | |
176 | * | |
177 | * Sets the name of the channel, which serves as an aid | |
178 | * to debugging. The name is used when creating GSource | |
179 | * watches for this channel. | |
180 | */ | |
181 | void qio_channel_set_name(QIOChannel *ioc, | |
182 | const char *name); | |
183 | ||
666a3af9 DB |
184 | /** |
185 | * qio_channel_readv_full: | |
186 | * @ioc: the channel object | |
187 | * @iov: the array of memory regions to read data into | |
188 | * @niov: the length of the @iov array | |
189 | * @fds: pointer to an array that will received file handles | |
190 | * @nfds: pointer filled with number of elements in @fds on return | |
821791b5 | 191 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
192 | * |
193 | * Read data from the IO channel, storing it in the | |
194 | * memory regions referenced by @iov. Each element | |
195 | * in the @iov will be fully populated with data | |
196 | * before the next one is used. The @niov parameter | |
197 | * specifies the total number of elements in @iov. | |
198 | * | |
199 | * It is not required for all @iov to be filled with | |
200 | * data. If the channel is in blocking mode, at least | |
201 | * one byte of data will be read, but no more is | |
202 | * guaranteed. If the channel is non-blocking and no | |
203 | * data is available, it will return QIO_CHANNEL_ERR_BLOCK | |
204 | * | |
205 | * If the channel has passed any file descriptors, | |
206 | * the @fds array pointer will be allocated and | |
207 | * the elements filled with the received file | |
208 | * descriptors. The @nfds pointer will be updated | |
209 | * to indicate the size of the @fds array that | |
210 | * was allocated. It is the callers responsibility | |
211 | * to call close() on each file descriptor and to | |
212 | * call g_free() on the array pointer in @fds. | |
213 | * | |
214 | * It is an error to pass a non-NULL @fds parameter | |
215 | * unless qio_channel_has_feature() returns a true | |
216 | * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. | |
217 | * | |
218 | * Returns: the number of bytes read, or -1 on error, | |
219 | * or QIO_CHANNEL_ERR_BLOCK if no data is available | |
220 | * and the channel is non-blocking | |
221 | */ | |
222 | ssize_t qio_channel_readv_full(QIOChannel *ioc, | |
223 | const struct iovec *iov, | |
224 | size_t niov, | |
225 | int **fds, | |
226 | size_t *nfds, | |
227 | Error **errp); | |
228 | ||
229 | ||
230 | /** | |
231 | * qio_channel_writev_full: | |
232 | * @ioc: the channel object | |
233 | * @iov: the array of memory regions to write data from | |
234 | * @niov: the length of the @iov array | |
235 | * @fds: an array of file handles to send | |
236 | * @nfds: number of file handles in @fds | |
b88651cb | 237 | * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*) |
821791b5 | 238 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
239 | * |
240 | * Write data to the IO channel, reading it from the | |
241 | * memory regions referenced by @iov. Each element | |
242 | * in the @iov will be fully sent, before the next | |
243 | * one is used. The @niov parameter specifies the | |
244 | * total number of elements in @iov. | |
245 | * | |
246 | * It is not required for all @iov data to be fully | |
247 | * sent. If the channel is in blocking mode, at least | |
248 | * one byte of data will be sent, but no more is | |
249 | * guaranteed. If the channel is non-blocking and no | |
250 | * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK | |
251 | * | |
252 | * If there are file descriptors to send, the @fds | |
253 | * array should be non-NULL and provide the handles. | |
254 | * All file descriptors will be sent if at least one | |
255 | * byte of data was sent. | |
256 | * | |
257 | * It is an error to pass a non-NULL @fds parameter | |
258 | * unless qio_channel_has_feature() returns a true | |
259 | * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. | |
260 | * | |
261 | * Returns: the number of bytes sent, or -1 on error, | |
262 | * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent | |
263 | * and the channel is non-blocking | |
264 | */ | |
265 | ssize_t qio_channel_writev_full(QIOChannel *ioc, | |
266 | const struct iovec *iov, | |
267 | size_t niov, | |
268 | int *fds, | |
269 | size_t nfds, | |
b88651cb | 270 | int flags, |
666a3af9 DB |
271 | Error **errp); |
272 | ||
e8ffaa31 EB |
273 | /** |
274 | * qio_channel_readv_all_eof: | |
275 | * @ioc: the channel object | |
276 | * @iov: the array of memory regions to read data into | |
277 | * @niov: the length of the @iov array | |
278 | * @errp: pointer to a NULL-initialized error object | |
279 | * | |
280 | * Read data from the IO channel, storing it in the | |
281 | * memory regions referenced by @iov. Each element | |
282 | * in the @iov will be fully populated with data | |
283 | * before the next one is used. The @niov parameter | |
284 | * specifies the total number of elements in @iov. | |
285 | * | |
286 | * The function will wait for all requested data | |
287 | * to be read, yielding from the current coroutine | |
288 | * if required. | |
289 | * | |
290 | * If end-of-file occurs before any data is read, | |
291 | * no error is reported; otherwise, if it occurs | |
292 | * before all requested data has been read, an error | |
293 | * will be reported. | |
294 | * | |
295 | * Returns: 1 if all bytes were read, 0 if end-of-file | |
296 | * occurs without data, or -1 on error | |
297 | */ | |
298 | int qio_channel_readv_all_eof(QIOChannel *ioc, | |
299 | const struct iovec *iov, | |
300 | size_t niov, | |
301 | Error **errp); | |
302 | ||
d4622e55 DB |
303 | /** |
304 | * qio_channel_readv_all: | |
305 | * @ioc: the channel object | |
306 | * @iov: the array of memory regions to read data into | |
307 | * @niov: the length of the @iov array | |
308 | * @errp: pointer to a NULL-initialized error object | |
309 | * | |
310 | * Read data from the IO channel, storing it in the | |
311 | * memory regions referenced by @iov. Each element | |
312 | * in the @iov will be fully populated with data | |
313 | * before the next one is used. The @niov parameter | |
314 | * specifies the total number of elements in @iov. | |
315 | * | |
316 | * The function will wait for all requested data | |
317 | * to be read, yielding from the current coroutine | |
318 | * if required. | |
319 | * | |
320 | * If end-of-file occurs before all requested data | |
321 | * has been read, an error will be reported. | |
322 | * | |
323 | * Returns: 0 if all bytes were read, or -1 on error | |
324 | */ | |
325 | int qio_channel_readv_all(QIOChannel *ioc, | |
326 | const struct iovec *iov, | |
327 | size_t niov, | |
328 | Error **errp); | |
329 | ||
330 | ||
331 | /** | |
332 | * qio_channel_writev_all: | |
333 | * @ioc: the channel object | |
334 | * @iov: the array of memory regions to write data from | |
335 | * @niov: the length of the @iov array | |
336 | * @errp: pointer to a NULL-initialized error object | |
337 | * | |
338 | * Write data to the IO channel, reading it from the | |
339 | * memory regions referenced by @iov. Each element | |
340 | * in the @iov will be fully sent, before the next | |
341 | * one is used. The @niov parameter specifies the | |
342 | * total number of elements in @iov. | |
343 | * | |
344 | * The function will wait for all requested data | |
345 | * to be written, yielding from the current coroutine | |
346 | * if required. | |
347 | * | |
348 | * Returns: 0 if all bytes were written, or -1 on error | |
349 | */ | |
350 | int qio_channel_writev_all(QIOChannel *ioc, | |
351 | const struct iovec *iov, | |
352 | size_t niov, | |
353 | Error **erp); | |
354 | ||
666a3af9 DB |
355 | /** |
356 | * qio_channel_readv: | |
357 | * @ioc: the channel object | |
358 | * @iov: the array of memory regions to read data into | |
359 | * @niov: the length of the @iov array | |
821791b5 | 360 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
361 | * |
362 | * Behaves as qio_channel_readv_full() but does not support | |
363 | * receiving of file handles. | |
364 | */ | |
365 | ssize_t qio_channel_readv(QIOChannel *ioc, | |
366 | const struct iovec *iov, | |
367 | size_t niov, | |
368 | Error **errp); | |
369 | ||
370 | /** | |
371 | * qio_channel_writev: | |
372 | * @ioc: the channel object | |
373 | * @iov: the array of memory regions to write data from | |
374 | * @niov: the length of the @iov array | |
821791b5 | 375 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
376 | * |
377 | * Behaves as qio_channel_writev_full() but does not support | |
378 | * sending of file handles. | |
379 | */ | |
380 | ssize_t qio_channel_writev(QIOChannel *ioc, | |
381 | const struct iovec *iov, | |
382 | size_t niov, | |
383 | Error **errp); | |
384 | ||
385 | /** | |
50ea44f0 | 386 | * qio_channel_read: |
666a3af9 DB |
387 | * @ioc: the channel object |
388 | * @buf: the memory region to read data into | |
389 | * @buflen: the length of @buf | |
821791b5 | 390 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
391 | * |
392 | * Behaves as qio_channel_readv_full() but does not support | |
393 | * receiving of file handles, and only supports reading into | |
394 | * a single memory region. | |
395 | */ | |
396 | ssize_t qio_channel_read(QIOChannel *ioc, | |
397 | char *buf, | |
398 | size_t buflen, | |
399 | Error **errp); | |
400 | ||
401 | /** | |
61f7c6a0 | 402 | * qio_channel_write: |
666a3af9 DB |
403 | * @ioc: the channel object |
404 | * @buf: the memory regions to send data from | |
405 | * @buflen: the length of @buf | |
821791b5 | 406 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
407 | * |
408 | * Behaves as qio_channel_writev_full() but does not support | |
409 | * sending of file handles, and only supports writing from a | |
410 | * single memory region. | |
411 | */ | |
412 | ssize_t qio_channel_write(QIOChannel *ioc, | |
413 | const char *buf, | |
414 | size_t buflen, | |
415 | Error **errp); | |
416 | ||
e8ffaa31 EB |
417 | /** |
418 | * qio_channel_read_all_eof: | |
419 | * @ioc: the channel object | |
420 | * @buf: the memory region to read data into | |
421 | * @buflen: the number of bytes to @buf | |
422 | * @errp: pointer to a NULL-initialized error object | |
423 | * | |
424 | * Reads @buflen bytes into @buf, possibly blocking or (if the | |
425 | * channel is non-blocking) yielding from the current coroutine | |
426 | * multiple times until the entire content is read. If end-of-file | |
427 | * occurs immediately it is not an error, but if it occurs after | |
428 | * data has been read it will return an error rather than a | |
429 | * short-read. Otherwise behaves as qio_channel_read(). | |
430 | * | |
431 | * Returns: 1 if all bytes were read, 0 if end-of-file occurs | |
432 | * without data, or -1 on error | |
433 | */ | |
434 | int qio_channel_read_all_eof(QIOChannel *ioc, | |
435 | char *buf, | |
436 | size_t buflen, | |
437 | Error **errp); | |
438 | ||
d4622e55 DB |
439 | /** |
440 | * qio_channel_read_all: | |
441 | * @ioc: the channel object | |
442 | * @buf: the memory region to read data into | |
443 | * @buflen: the number of bytes to @buf | |
444 | * @errp: pointer to a NULL-initialized error object | |
445 | * | |
446 | * Reads @buflen bytes into @buf, possibly blocking or (if the | |
447 | * channel is non-blocking) yielding from the current coroutine | |
448 | * multiple times until the entire content is read. If end-of-file | |
449 | * occurs it will return an error rather than a short-read. Otherwise | |
450 | * behaves as qio_channel_read(). | |
451 | * | |
452 | * Returns: 0 if all bytes were read, or -1 on error | |
453 | */ | |
454 | int qio_channel_read_all(QIOChannel *ioc, | |
455 | char *buf, | |
456 | size_t buflen, | |
457 | Error **errp); | |
e8ffaa31 | 458 | |
d4622e55 DB |
459 | /** |
460 | * qio_channel_write_all: | |
461 | * @ioc: the channel object | |
462 | * @buf: the memory region to write data into | |
463 | * @buflen: the number of bytes to @buf | |
464 | * @errp: pointer to a NULL-initialized error object | |
465 | * | |
466 | * Writes @buflen bytes from @buf, possibly blocking or (if the | |
467 | * channel is non-blocking) yielding from the current coroutine | |
468 | * multiple times until the entire content is written. Otherwise | |
469 | * behaves as qio_channel_write(). | |
470 | * | |
471 | * Returns: 0 if all bytes were written, or -1 on error | |
472 | */ | |
473 | int qio_channel_write_all(QIOChannel *ioc, | |
474 | const char *buf, | |
475 | size_t buflen, | |
476 | Error **errp); | |
477 | ||
666a3af9 DB |
478 | /** |
479 | * qio_channel_set_blocking: | |
480 | * @ioc: the channel object | |
481 | * @enabled: the blocking flag state | |
821791b5 | 482 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
483 | * |
484 | * If @enabled is true, then the channel is put into | |
485 | * blocking mode, otherwise it will be non-blocking. | |
486 | * | |
487 | * In non-blocking mode, read/write operations may | |
488 | * return QIO_CHANNEL_ERR_BLOCK if they would otherwise | |
489 | * block on I/O | |
490 | */ | |
491 | int qio_channel_set_blocking(QIOChannel *ioc, | |
492 | bool enabled, | |
493 | Error **errp); | |
494 | ||
495 | /** | |
496 | * qio_channel_close: | |
497 | * @ioc: the channel object | |
821791b5 | 498 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
499 | * |
500 | * Close the channel, flushing any pending I/O | |
501 | * | |
502 | * Returns: 0 on success, -1 on error | |
503 | */ | |
504 | int qio_channel_close(QIOChannel *ioc, | |
505 | Error **errp); | |
506 | ||
507 | /** | |
508 | * qio_channel_shutdown: | |
509 | * @ioc: the channel object | |
510 | * @how: the direction to shutdown | |
821791b5 | 511 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
512 | * |
513 | * Shutdowns transmission and/or receiving of data | |
514 | * without closing the underlying transport. | |
515 | * | |
516 | * Not all implementations will support this facility, | |
517 | * so may report an error. To avoid errors, the | |
518 | * caller may check for the feature flag | |
519 | * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling | |
520 | * this method. | |
521 | * | |
8659f317 LS |
522 | * This function is thread-safe, terminates quickly and does not block. |
523 | * | |
666a3af9 DB |
524 | * Returns: 0 on success, -1 on error |
525 | */ | |
526 | int qio_channel_shutdown(QIOChannel *ioc, | |
527 | QIOChannelShutdown how, | |
528 | Error **errp); | |
529 | ||
530 | /** | |
531 | * qio_channel_set_delay: | |
532 | * @ioc: the channel object | |
533 | * @enabled: the new flag state | |
534 | * | |
535 | * Controls whether the underlying transport is | |
536 | * permitted to delay writes in order to merge | |
537 | * small packets. If @enabled is true, then the | |
538 | * writes may be delayed in order to opportunistically | |
539 | * merge small packets into larger ones. If @enabled | |
540 | * is false, writes are dispatched immediately with | |
541 | * no delay. | |
542 | * | |
543 | * When @enabled is false, applications may wish to | |
544 | * use the qio_channel_set_cork() method to explicitly | |
545 | * control write merging. | |
546 | * | |
547 | * On channels which are backed by a socket, this | |
548 | * API corresponds to the inverse of TCP_NODELAY flag, | |
549 | * controlling whether the Nagle algorithm is active. | |
550 | * | |
551 | * This setting is merely a hint, so implementations are | |
552 | * free to ignore this without it being considered an | |
553 | * error. | |
554 | */ | |
555 | void qio_channel_set_delay(QIOChannel *ioc, | |
556 | bool enabled); | |
557 | ||
558 | /** | |
559 | * qio_channel_set_cork: | |
560 | * @ioc: the channel object | |
561 | * @enabled: the new flag state | |
562 | * | |
563 | * Controls whether the underlying transport is | |
564 | * permitted to dispatch data that is written. | |
565 | * If @enabled is true, then any data written will | |
566 | * be queued in local buffers until @enabled is | |
567 | * set to false once again. | |
568 | * | |
569 | * This feature is typically used when the automatic | |
570 | * write coalescing facility is disabled via the | |
571 | * qio_channel_set_delay() method. | |
572 | * | |
573 | * On channels which are backed by a socket, this | |
574 | * API corresponds to the TCP_CORK flag. | |
575 | * | |
576 | * This setting is merely a hint, so implementations are | |
577 | * free to ignore this without it being considered an | |
578 | * error. | |
579 | */ | |
580 | void qio_channel_set_cork(QIOChannel *ioc, | |
581 | bool enabled); | |
582 | ||
583 | ||
584 | /** | |
585 | * qio_channel_seek: | |
586 | * @ioc: the channel object | |
587 | * @offset: the position to seek to, relative to @whence | |
588 | * @whence: one of the (POSIX) SEEK_* constants listed below | |
821791b5 | 589 | * @errp: pointer to a NULL-initialized error object |
666a3af9 DB |
590 | * |
591 | * Moves the current I/O position within the channel | |
592 | * @ioc, to be @offset. The value of @offset is | |
593 | * interpreted relative to @whence: | |
594 | * | |
595 | * SEEK_SET - the position is set to @offset bytes | |
596 | * SEEK_CUR - the position is moved by @offset bytes | |
597 | * SEEK_END - the position is set to end of the file plus @offset bytes | |
598 | * | |
599 | * Not all implementations will support this facility, | |
600 | * so may report an error. | |
601 | * | |
602 | * Returns: the new position on success, (off_t)-1 on failure | |
603 | */ | |
604 | off_t qio_channel_io_seek(QIOChannel *ioc, | |
605 | off_t offset, | |
606 | int whence, | |
607 | Error **errp); | |
608 | ||
609 | ||
610 | /** | |
611 | * qio_channel_create_watch: | |
612 | * @ioc: the channel object | |
613 | * @condition: the I/O condition to monitor | |
614 | * | |
615 | * Create a new main loop source that is used to watch | |
616 | * for the I/O condition @condition. Typically the | |
617 | * qio_channel_add_watch() method would be used instead | |
618 | * of this, since it directly attaches a callback to | |
619 | * the source | |
620 | * | |
621 | * Returns: the new main loop source. | |
622 | */ | |
623 | GSource *qio_channel_create_watch(QIOChannel *ioc, | |
624 | GIOCondition condition); | |
625 | ||
626 | /** | |
627 | * qio_channel_add_watch: | |
628 | * @ioc: the channel object | |
629 | * @condition: the I/O condition to monitor | |
630 | * @func: callback to invoke when the source becomes ready | |
631 | * @user_data: opaque data to pass to @func | |
632 | * @notify: callback to free @user_data | |
633 | * | |
634 | * Create a new main loop source that is used to watch | |
635 | * for the I/O condition @condition. The callback @func | |
636 | * will be registered against the source, to be invoked | |
637 | * when the source becomes ready. The optional @user_data | |
638 | * will be passed to @func when it is invoked. The @notify | |
639 | * callback will be used to free @user_data when the | |
640 | * watch is deleted | |
641 | * | |
642 | * The returned source ID can be used with g_source_remove() | |
643 | * to remove and free the source when no longer required. | |
644 | * Alternatively the @func callback can return a FALSE | |
645 | * value. | |
646 | * | |
647 | * Returns: the source ID | |
648 | */ | |
649 | guint qio_channel_add_watch(QIOChannel *ioc, | |
650 | GIOCondition condition, | |
651 | QIOChannelFunc func, | |
652 | gpointer user_data, | |
653 | GDestroyNotify notify); | |
654 | ||
315409c7 PX |
655 | /** |
656 | * qio_channel_add_watch_full: | |
657 | * @ioc: the channel object | |
658 | * @condition: the I/O condition to monitor | |
659 | * @func: callback to invoke when the source becomes ready | |
660 | * @user_data: opaque data to pass to @func | |
661 | * @notify: callback to free @user_data | |
662 | * @context: the context to run the watch source | |
663 | * | |
664 | * Similar as qio_channel_add_watch(), but allows to specify context | |
665 | * to run the watch source. | |
666 | * | |
667 | * Returns: the source ID | |
668 | */ | |
669 | guint qio_channel_add_watch_full(QIOChannel *ioc, | |
670 | GIOCondition condition, | |
671 | QIOChannelFunc func, | |
672 | gpointer user_data, | |
673 | GDestroyNotify notify, | |
674 | GMainContext *context); | |
675 | ||
676 | /** | |
677 | * qio_channel_add_watch_source: | |
678 | * @ioc: the channel object | |
679 | * @condition: the I/O condition to monitor | |
680 | * @func: callback to invoke when the source becomes ready | |
681 | * @user_data: opaque data to pass to @func | |
682 | * @notify: callback to free @user_data | |
683 | * @context: gcontext to bind the source to | |
684 | * | |
685 | * Similar as qio_channel_add_watch(), but allows to specify context | |
686 | * to run the watch source, meanwhile return the GSource object | |
687 | * instead of tag ID, with the GSource referenced already. | |
688 | * | |
689 | * Note: callers is responsible to unref the source when not needed. | |
690 | * | |
691 | * Returns: the source pointer | |
692 | */ | |
693 | GSource *qio_channel_add_watch_source(QIOChannel *ioc, | |
694 | GIOCondition condition, | |
695 | QIOChannelFunc func, | |
696 | gpointer user_data, | |
697 | GDestroyNotify notify, | |
698 | GMainContext *context); | |
666a3af9 | 699 | |
c4c497d2 PB |
700 | /** |
701 | * qio_channel_attach_aio_context: | |
702 | * @ioc: the channel object | |
703 | * @ctx: the #AioContext to set the handlers on | |
704 | * | |
705 | * Request that qio_channel_yield() sets I/O handlers on | |
706 | * the given #AioContext. If @ctx is %NULL, qio_channel_yield() | |
707 | * uses QEMU's main thread event loop. | |
708 | * | |
709 | * You can move a #QIOChannel from one #AioContext to another even if | |
710 | * I/O handlers are set for a coroutine. However, #QIOChannel provides | |
711 | * no synchronization between the calls to qio_channel_yield() and | |
712 | * qio_channel_attach_aio_context(). | |
713 | * | |
714 | * Therefore you should first call qio_channel_detach_aio_context() | |
715 | * to ensure that the coroutine is not entered concurrently. Then, | |
716 | * while the coroutine has yielded, call qio_channel_attach_aio_context(), | |
717 | * and then aio_co_schedule() to place the coroutine on the new | |
718 | * #AioContext. The calls to qio_channel_detach_aio_context() | |
719 | * and qio_channel_attach_aio_context() should be protected with | |
720 | * aio_context_acquire() and aio_context_release(). | |
721 | */ | |
722 | void qio_channel_attach_aio_context(QIOChannel *ioc, | |
723 | AioContext *ctx); | |
724 | ||
725 | /** | |
726 | * qio_channel_detach_aio_context: | |
727 | * @ioc: the channel object | |
728 | * | |
729 | * Disable any I/O handlers set by qio_channel_yield(). With the | |
730 | * help of aio_co_schedule(), this allows moving a coroutine that was | |
731 | * paused by qio_channel_yield() to another context. | |
732 | */ | |
733 | void qio_channel_detach_aio_context(QIOChannel *ioc); | |
734 | ||
666a3af9 DB |
735 | /** |
736 | * qio_channel_yield: | |
737 | * @ioc: the channel object | |
738 | * @condition: the I/O condition to wait for | |
739 | * | |
c4c497d2 PB |
740 | * Yields execution from the current coroutine until the condition |
741 | * indicated by @condition becomes available. @condition must | |
742 | * be either %G_IO_IN or %G_IO_OUT; it cannot contain both. In | |
743 | * addition, no two coroutine can be waiting on the same condition | |
744 | * and channel at the same time. | |
666a3af9 | 745 | * |
6886ceaf KW |
746 | * This must only be called from coroutine context. It is safe to |
747 | * reenter the coroutine externally while it is waiting; in this | |
748 | * case the function will return even if @condition is not yet | |
749 | * available. | |
666a3af9 | 750 | */ |
6886ceaf KW |
751 | void coroutine_fn qio_channel_yield(QIOChannel *ioc, |
752 | GIOCondition condition); | |
666a3af9 DB |
753 | |
754 | /** | |
755 | * qio_channel_wait: | |
756 | * @ioc: the channel object | |
757 | * @condition: the I/O condition to wait for | |
758 | * | |
759 | * Block execution from the current thread until | |
760 | * the condition indicated by @condition becomes | |
761 | * available. | |
762 | * | |
763 | * This will enter a nested event loop to perform | |
764 | * the wait. | |
765 | */ | |
766 | void qio_channel_wait(QIOChannel *ioc, | |
767 | GIOCondition condition); | |
768 | ||
bf88c124 PB |
769 | /** |
770 | * qio_channel_set_aio_fd_handler: | |
771 | * @ioc: the channel object | |
772 | * @ctx: the AioContext to set the handlers on | |
773 | * @io_read: the read handler | |
774 | * @io_write: the write handler | |
775 | * @opaque: the opaque value passed to the handler | |
776 | * | |
777 | * This is used internally by qio_channel_yield(). It can | |
778 | * be used by channel implementations to forward the handlers | |
779 | * to another channel (e.g. from #QIOChannelTLS to the | |
780 | * underlying socket). | |
781 | */ | |
782 | void qio_channel_set_aio_fd_handler(QIOChannel *ioc, | |
783 | AioContext *ctx, | |
784 | IOHandler *io_read, | |
785 | IOHandler *io_write, | |
786 | void *opaque); | |
787 | ||
bebab91e EU |
788 | /** |
789 | * qio_channel_readv_full_all_eof: | |
790 | * @ioc: the channel object | |
791 | * @iov: the array of memory regions to read data to | |
792 | * @niov: the length of the @iov array | |
793 | * @fds: an array of file handles to read | |
794 | * @nfds: number of file handles in @fds | |
795 | * @errp: pointer to a NULL-initialized error object | |
796 | * | |
797 | * | |
798 | * Performs same function as qio_channel_readv_all_eof. | |
799 | * Additionally, attempts to read file descriptors shared | |
800 | * over the channel. The function will wait for all | |
801 | * requested data to be read, yielding from the current | |
802 | * coroutine if required. data refers to both file | |
803 | * descriptors and the iovs. | |
804 | * | |
805 | * Returns: 1 if all bytes were read, 0 if end-of-file | |
806 | * occurs without data, or -1 on error | |
807 | */ | |
808 | ||
809 | int qio_channel_readv_full_all_eof(QIOChannel *ioc, | |
810 | const struct iovec *iov, | |
811 | size_t niov, | |
812 | int **fds, size_t *nfds, | |
813 | Error **errp); | |
814 | ||
815 | /** | |
816 | * qio_channel_readv_full_all: | |
817 | * @ioc: the channel object | |
818 | * @iov: the array of memory regions to read data to | |
819 | * @niov: the length of the @iov array | |
820 | * @fds: an array of file handles to read | |
821 | * @nfds: number of file handles in @fds | |
822 | * @errp: pointer to a NULL-initialized error object | |
823 | * | |
824 | * | |
825 | * Performs same function as qio_channel_readv_all_eof. | |
826 | * Additionally, attempts to read file descriptors shared | |
827 | * over the channel. The function will wait for all | |
828 | * requested data to be read, yielding from the current | |
829 | * coroutine if required. data refers to both file | |
830 | * descriptors and the iovs. | |
831 | * | |
832 | * Returns: 0 if all bytes were read, or -1 on error | |
833 | */ | |
834 | ||
835 | int qio_channel_readv_full_all(QIOChannel *ioc, | |
836 | const struct iovec *iov, | |
837 | size_t niov, | |
838 | int **fds, size_t *nfds, | |
839 | Error **errp); | |
840 | ||
bfa42387 EU |
841 | /** |
842 | * qio_channel_writev_full_all: | |
843 | * @ioc: the channel object | |
844 | * @iov: the array of memory regions to write data from | |
845 | * @niov: the length of the @iov array | |
846 | * @fds: an array of file handles to send | |
847 | * @nfds: number of file handles in @fds | |
b88651cb | 848 | * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*) |
bfa42387 EU |
849 | * @errp: pointer to a NULL-initialized error object |
850 | * | |
851 | * | |
852 | * Behaves like qio_channel_writev_full but will attempt | |
853 | * to send all data passed (file handles and memory regions). | |
854 | * The function will wait for all requested data | |
855 | * to be written, yielding from the current coroutine | |
856 | * if required. | |
857 | * | |
b88651cb LB |
858 | * If QIO_CHANNEL_WRITE_FLAG_ZERO_COPY is passed in flags, |
859 | * instead of waiting for all requested data to be written, | |
860 | * this function will wait until it's all queued for writing. | |
861 | * In this case, if the buffer gets changed between queueing and | |
862 | * sending, the updated buffer will be sent. If this is not a | |
863 | * desired behavior, it's suggested to call qio_channel_flush() | |
864 | * before reusing the buffer. | |
865 | * | |
bfa42387 EU |
866 | * Returns: 0 if all bytes were written, or -1 on error |
867 | */ | |
868 | ||
869 | int qio_channel_writev_full_all(QIOChannel *ioc, | |
870 | const struct iovec *iov, | |
871 | size_t niov, | |
872 | int *fds, size_t nfds, | |
b88651cb LB |
873 | int flags, Error **errp); |
874 | ||
875 | /** | |
876 | * qio_channel_flush: | |
877 | * @ioc: the channel object | |
878 | * @errp: pointer to a NULL-initialized error object | |
879 | * | |
880 | * Will block until every packet queued with | |
881 | * qio_channel_writev_full() + QIO_CHANNEL_WRITE_FLAG_ZERO_COPY | |
882 | * is sent, or return in case of any error. | |
883 | * | |
884 | * If not implemented, acts as a no-op, and returns 0. | |
885 | * | |
886 | * Returns -1 if any error is found, | |
887 | * 1 if every send failed to use zero copy. | |
888 | * 0 otherwise. | |
889 | */ | |
890 | ||
891 | int qio_channel_flush(QIOChannel *ioc, | |
892 | Error **errp); | |
bfa42387 | 893 | |
2a6a4076 | 894 | #endif /* QIO_CHANNEL_H */ |