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 */ 859