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