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