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