include/io/channel.h

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