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