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