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