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