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