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 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  *
  19  */
  20
  21 #ifndef QIO_CHANNEL_H
  22 #define QIO_CHANNEL_H
  23
  24 #include "qom/object.h"
  25 #include "qemu/coroutine.h"
  26 #include "block/aio.h"
  27
  28 #define TYPE_QIO_CHANNEL "qio-channel"
  29 OBJECT_DECLARE_TYPE(QIOChannel, QIOChannelClass,
  30                     qio_channel, QIO_CHANNEL)
  31
  32
  33 #define QIO_CHANNEL_ERR_BLOCK -2
  34
  35 typedef enum QIOChannelFeature QIOChannelFeature;
  36
  37 enum QIOChannelFeature {
  38     QIO_CHANNEL_FEATURE_FD_PASS,
  39     QIO_CHANNEL_FEATURE_SHUTDOWN,
  40     QIO_CHANNEL_FEATURE_LISTEN,
  41 };
  42
  43
  44 typedef enum QIOChannelShutdown QIOChannelShutdown;
  45
  46 enum QIOChannelShutdown {
  47     QIO_CHANNEL_SHUTDOWN_READ = 1,
  48     QIO_CHANNEL_SHUTDOWN_WRITE = 2,
  49     QIO_CHANNEL_SHUTDOWN_BOTH = 3,
  50 };
  51
  52 typedef gboolean (*QIOChannelFunc)(QIOChannel *ioc,
  53                                    GIOCondition condition,
  54                                    gpointer data);
  55
  56 /**
  57  * QIOChannel:
  58  *
  59  * The QIOChannel defines the core API for a generic I/O channel
  60  * class hierarchy. It is inspired by GIOChannel, but has the
  61  * following differences
  62  *
  63  *  - Use QOM to properly support arbitrary subclassing
  64  *  - Support use of iovecs for efficient I/O with multiple blocks
  65  *  - None of the character set translation, binary data exclusively
  66  *  - Direct support for QEMU Error object reporting
  67  *  - File descriptor passing
  68  *
  69  * This base class is abstract so cannot be instantiated. There
  70  * will be subclasses for dealing with sockets, files, and higher
  71  * level protocols such as TLS, WebSocket, etc.
  72  */
  73
  74 struct QIOChannel {
  75     Object parent;
  76     unsigned int features; /* bitmask of QIOChannelFeatures */
  77     char *name;
  78     AioContext *ctx;
  79     Coroutine *read_coroutine;
  80     Coroutine *write_coroutine;
  81 #ifdef _WIN32
  82     HANDLE event; /* For use with GSource on Win32 */
  83 #endif
  84 };
  85
  86 /**
  87  * QIOChannelClass:
  88  *
  89  * This class defines the contract that all subclasses
  90  * must follow to provide specific channel implementations.
  91  * The first five callbacks are mandatory to support, others
  92  * provide additional optional features.
  93  *
  94  * Consult the corresponding public API docs for a description
  95  * of the semantics of each callback
  96  */
  97 struct QIOChannelClass {
  98     ObjectClass parent;
  99
 100     /* Mandatory callbacks */
 101     ssize_t (*io_writev)(QIOChannel *ioc,
 102                          const struct iovec *iov,
 103                          size_t niov,
 104                          int *fds,
 105                          size_t nfds,
 106                          Error **errp);
 107     ssize_t (*io_readv)(QIOChannel *ioc,
 108                         const struct iovec *iov,
 109                         size_t niov,
 110                         int **fds,
 111                         size_t *nfds,
 112                         Error **errp);
 113     int (*io_close)(QIOChannel *ioc,
 114                     Error **errp);
 115     GSource * (*io_create_watch)(QIOChannel *ioc,
 116                                  GIOCondition condition);
 117     int (*io_set_blocking)(QIOChannel *ioc,
 118                            bool enabled,
 119                            Error **errp);
 120
 121     /* Optional callbacks */
 122     int (*io_shutdown)(QIOChannel *ioc,
 123                        QIOChannelShutdown how,
 124                        Error **errp);
 125     void (*io_set_cork)(QIOChannel *ioc,
 126                         bool enabled);
 127     void (*io_set_delay)(QIOChannel *ioc,
 128                          bool enabled);
 129     off_t (*io_seek)(QIOChannel *ioc,
 130                      off_t offset,
 131                      int whence,
 132                      Error **errp);
 133     void (*io_set_aio_fd_handler)(QIOChannel *ioc,
 134                                   AioContext *ctx,
 135                                   IOHandler *io_read,
 136                                   IOHandler *io_write,
 137                                   void *opaque);
 138 };
 139
 140 /* General I/O handling functions */
 141
 142 /**
 143  * qio_channel_has_feature:
 144  * @ioc: the channel object
 145  * @feature: the feature to check support of
 146  *
 147  * Determine whether the channel implementation supports
 148  * the optional feature named in @feature.
 149  *
 150  * Returns: true if supported, false otherwise.
 151  */
 152 bool qio_channel_has_feature(QIOChannel *ioc,
 153                              QIOChannelFeature feature);
 154
 155 /**
 156  * qio_channel_set_feature:
 157  * @ioc: the channel object
 158  * @feature: the feature to set support for
 159  *
 160  * Add channel support for the feature named in @feature.
 161  */
 162 void qio_channel_set_feature(QIOChannel *ioc,
 163                              QIOChannelFeature feature);
 164
 165 /**
 166  * qio_channel_set_name:
 167  * @ioc: the channel object
 168  * @name: the name of the channel
 169  *
 170  * Sets the name of the channel, which serves as an aid
 171  * to debugging. The name is used when creating GSource
 172  * watches for this channel.
 173  */
 174 void qio_channel_set_name(QIOChannel *ioc,
 175                           const char *name);
 176
 177 /**
 178  * qio_channel_readv_full:
 179  * @ioc: the channel object
 180  * @iov: the array of memory regions to read data into
 181  * @niov: the length of the @iov array
 182  * @fds: pointer to an array that will received file handles
 183  * @nfds: pointer filled with number of elements in @fds on return
 184  * @errp: pointer to a NULL-initialized error object
 185  *
 186  * Read data from the IO channel, storing it in the
 187  * memory regions referenced by @iov. Each element
 188  * in the @iov will be fully populated with data
 189  * before the next one is used. The @niov parameter
 190  * specifies the total number of elements in @iov.
 191  *
 192  * It is not required for all @iov to be filled with
 193  * data. If the channel is in blocking mode, at least
 194  * one byte of data will be read, but no more is
 195  * guaranteed. If the channel is non-blocking and no
 196  * data is available, it will return QIO_CHANNEL_ERR_BLOCK
 197  *
 198  * If the channel has passed any file descriptors,
 199  * the @fds array pointer will be allocated and
 200  * the elements filled with the received file
 201  * descriptors. The @nfds pointer will be updated
 202  * to indicate the size of the @fds array that
 203  * was allocated. It is the callers responsibility
 204  * to call close() on each file descriptor and to
 205  * call g_free() on the array pointer in @fds.
 206  *
 207  * It is an error to pass a non-NULL @fds parameter
 208  * unless qio_channel_has_feature() returns a true
 209  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
 210  *
 211  * Returns: the number of bytes read, or -1 on error,
 212  * or QIO_CHANNEL_ERR_BLOCK if no data is available
 213  * and the channel is non-blocking
 214  */
 215 ssize_t qio_channel_readv_full(QIOChannel *ioc,
 216                                const struct iovec *iov,
 217                                size_t niov,
 218                                int **fds,
 219                                size_t *nfds,
 220                                Error **errp);
 221
 222
 223 /**
 224  * qio_channel_writev_full:
 225  * @ioc: the channel object
 226  * @iov: the array of memory regions to write data from
 227  * @niov: the length of the @iov array
 228  * @fds: an array of file handles to send
 229  * @nfds: number of file handles in @fds
 230  * @errp: pointer to a NULL-initialized error object
 231  *
 232  * Write data to the IO channel, reading it from the
 233  * memory regions referenced by @iov. Each element
 234  * in the @iov will be fully sent, before the next
 235  * one is used. The @niov parameter specifies the
 236  * total number of elements in @iov.
 237  *
 238  * It is not required for all @iov data to be fully
 239  * sent. If the channel is in blocking mode, at least
 240  * one byte of data will be sent, but no more is
 241  * guaranteed. If the channel is non-blocking and no
 242  * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK
 243  *
 244  * If there are file descriptors to send, the @fds
 245  * array should be non-NULL and provide the handles.
 246  * All file descriptors will be sent if at least one
 247  * byte of data was sent.
 248  *
 249  * It is an error to pass a non-NULL @fds parameter
 250  * unless qio_channel_has_feature() returns a true
 251  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
 252  *
 253  * Returns: the number of bytes sent, or -1 on error,
 254  * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent
 255  * and the channel is non-blocking
 256  */
 257 ssize_t qio_channel_writev_full(QIOChannel *ioc,
 258                                 const struct iovec *iov,
 259                                 size_t niov,
 260                                 int *fds,
 261                                 size_t nfds,
 262                                 Error **errp);
 263
 264 /**
 265  * qio_channel_readv_all_eof:
 266  * @ioc: the channel object
 267  * @iov: the array of memory regions to read data into
 268  * @niov: the length of the @iov array
 269  * @errp: pointer to a NULL-initialized error object
 270  *
 271  * Read data from the IO channel, storing it in the
 272  * memory regions referenced by @iov. Each element
 273  * in the @iov will be fully populated with data
 274  * before the next one is used. The @niov parameter
 275  * specifies the total number of elements in @iov.
 276  *
 277  * The function will wait for all requested data
 278  * to be read, yielding from the current coroutine
 279  * if required.
 280  *
 281  * If end-of-file occurs before any data is read,
 282  * no error is reported; otherwise, if it occurs
 283  * before all requested data has been read, an error
 284  * will be reported.
 285  *
 286  * Returns: 1 if all bytes were read, 0 if end-of-file
 287  *          occurs without data, or -1 on error
 288  */
 289 int qio_channel_readv_all_eof(QIOChannel *ioc,
 290                               const struct iovec *iov,
 291                               size_t niov,
 292                               Error **errp);
 293
 294 /**
 295  * qio_channel_readv_all:
 296  * @ioc: the channel object
 297  * @iov: the array of memory regions to read data into
 298  * @niov: the length of the @iov array
 299  * @errp: pointer to a NULL-initialized error object
 300  *
 301  * Read data from the IO channel, storing it in the
 302  * memory regions referenced by @iov. Each element
 303  * in the @iov will be fully populated with data
 304  * before the next one is used. The @niov parameter
 305  * specifies the total number of elements in @iov.
 306  *
 307  * The function will wait for all requested data
 308  * to be read, yielding from the current coroutine
 309  * if required.
 310  *
 311  * If end-of-file occurs before all requested data
 312  * has been read, an error will be reported.
 313  *
 314  * Returns: 0 if all bytes were read, or -1 on error
 315  */
 316 int qio_channel_readv_all(QIOChannel *ioc,
 317                           const struct iovec *iov,
 318                           size_t niov,
 319                           Error **errp);
 320
 321
 322 /**
 323  * qio_channel_writev_all:
 324  * @ioc: the channel object
 325  * @iov: the array of memory regions to write data from
 326  * @niov: the length of the @iov array
 327  * @errp: pointer to a NULL-initialized error object
 328  *
 329  * Write data to the IO channel, reading it from the
 330  * memory regions referenced by @iov. Each element
 331  * in the @iov will be fully sent, before the next
 332  * one is used. The @niov parameter specifies the
 333  * total number of elements in @iov.
 334  *
 335  * The function will wait for all requested data
 336  * to be written, yielding from the current coroutine
 337  * if required.
 338  *
 339  * Returns: 0 if all bytes were written, or -1 on error
 340  */
 341 int qio_channel_writev_all(QIOChannel *ioc,
 342                            const struct iovec *iov,
 343                            size_t niov,
 344                            Error **erp);
 345
 346 /**
 347  * qio_channel_readv:
 348  * @ioc: the channel object
 349  * @iov: the array of memory regions to read data into
 350  * @niov: the length of the @iov array
 351  * @errp: pointer to a NULL-initialized error object
 352  *
 353  * Behaves as qio_channel_readv_full() but does not support
 354  * receiving of file handles.
 355  */
 356 ssize_t qio_channel_readv(QIOChannel *ioc,
 357                           const struct iovec *iov,
 358                           size_t niov,
 359                           Error **errp);
 360
 361 /**
 362  * qio_channel_writev:
 363  * @ioc: the channel object
 364  * @iov: the array of memory regions to write data from
 365  * @niov: the length of the @iov array
 366  * @errp: pointer to a NULL-initialized error object
 367  *
 368  * Behaves as qio_channel_writev_full() but does not support
 369  * sending of file handles.
 370  */
 371 ssize_t qio_channel_writev(QIOChannel *ioc,
 372                            const struct iovec *iov,
 373                            size_t niov,
 374                            Error **errp);
 375
 376 /**
 377  * qio_channel_read:
 378  * @ioc: the channel object
 379  * @buf: the memory region to read data into
 380  * @buflen: the length of @buf
 381  * @errp: pointer to a NULL-initialized error object
 382  *
 383  * Behaves as qio_channel_readv_full() but does not support
 384  * receiving of file handles, and only supports reading into
 385  * a single memory region.
 386  */
 387 ssize_t qio_channel_read(QIOChannel *ioc,
 388                          char *buf,
 389                          size_t buflen,
 390                          Error **errp);
 391
 392 /**
 393  * qio_channel_write:
 394  * @ioc: the channel object
 395  * @buf: the memory regions to send data from
 396  * @buflen: the length of @buf
 397  * @errp: pointer to a NULL-initialized error object
 398  *
 399  * Behaves as qio_channel_writev_full() but does not support
 400  * sending of file handles, and only supports writing from a
 401  * single memory region.
 402  */
 403 ssize_t qio_channel_write(QIOChannel *ioc,
 404                           const char *buf,
 405                           size_t buflen,
 406                           Error **errp);
 407
 408 /**
 409  * qio_channel_read_all_eof:
 410  * @ioc: the channel object
 411  * @buf: the memory region to read data into
 412  * @buflen: the number of bytes to @buf
 413  * @errp: pointer to a NULL-initialized error object
 414  *
 415  * Reads @buflen bytes into @buf, possibly blocking or (if the
 416  * channel is non-blocking) yielding from the current coroutine
 417  * multiple times until the entire content is read. If end-of-file
 418  * occurs immediately it is not an error, but if it occurs after
 419  * data has been read it will return an error rather than a
 420  * short-read. Otherwise behaves as qio_channel_read().
 421  *
 422  * Returns: 1 if all bytes were read, 0 if end-of-file occurs
 423  *          without data, or -1 on error
 424  */
 425 int qio_channel_read_all_eof(QIOChannel *ioc,
 426                              char *buf,
 427                              size_t buflen,
 428                              Error **errp);
 429
 430 /**
 431  * qio_channel_read_all:
 432  * @ioc: the channel object
 433  * @buf: the memory region to read data into
 434  * @buflen: the number of bytes to @buf
 435  * @errp: pointer to a NULL-initialized error object
 436  *
 437  * Reads @buflen bytes into @buf, possibly blocking or (if the
 438  * channel is non-blocking) yielding from the current coroutine
 439  * multiple times until the entire content is read. If end-of-file
 440  * occurs it will return an error rather than a short-read. Otherwise
 441  * behaves as qio_channel_read().
 442  *
 443  * Returns: 0 if all bytes were read, or -1 on error
 444  */
 445 int qio_channel_read_all(QIOChannel *ioc,
 446                          char *buf,
 447                          size_t buflen,
 448                          Error **errp);
 449
 450 /**
 451  * qio_channel_write_all:
 452  * @ioc: the channel object
 453  * @buf: the memory region to write data into
 454  * @buflen: the number of bytes to @buf
 455  * @errp: pointer to a NULL-initialized error object
 456  *
 457  * Writes @buflen bytes from @buf, possibly blocking or (if the
 458  * channel is non-blocking) yielding from the current coroutine
 459  * multiple times until the entire content is written.  Otherwise
 460  * behaves as qio_channel_write().
 461  *
 462  * Returns: 0 if all bytes were written, or -1 on error
 463  */
 464 int qio_channel_write_all(QIOChannel *ioc,
 465                           const char *buf,
 466                           size_t buflen,
 467                           Error **errp);
 468
 469 /**
 470  * qio_channel_set_blocking:
 471  * @ioc: the channel object
 472  * @enabled: the blocking flag state
 473  * @errp: pointer to a NULL-initialized error object
 474  *
 475  * If @enabled is true, then the channel is put into
 476  * blocking mode, otherwise it will be non-blocking.
 477  *
 478  * In non-blocking mode, read/write operations may
 479  * return QIO_CHANNEL_ERR_BLOCK if they would otherwise
 480  * block on I/O
 481  */
 482 int qio_channel_set_blocking(QIOChannel *ioc,
 483                              bool enabled,
 484                              Error **errp);
 485
 486 /**
 487  * qio_channel_close:
 488  * @ioc: the channel object
 489  * @errp: pointer to a NULL-initialized error object
 490  *
 491  * Close the channel, flushing any pending I/O
 492  *
 493  * Returns: 0 on success, -1 on error
 494  */
 495 int qio_channel_close(QIOChannel *ioc,
 496                       Error **errp);
 497
 498 /**
 499  * qio_channel_shutdown:
 500  * @ioc: the channel object
 501  * @how: the direction to shutdown
 502  * @errp: pointer to a NULL-initialized error object
 503  *
 504  * Shutdowns transmission and/or receiving of data
 505  * without closing the underlying transport.
 506  *
 507  * Not all implementations will support this facility,
 508  * so may report an error. To avoid errors, the
 509  * caller may check for the feature flag
 510  * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling
 511  * this method.
 512  *
 513  * Returns: 0 on success, -1 on error
 514  */
 515 int qio_channel_shutdown(QIOChannel *ioc,
 516                          QIOChannelShutdown how,
 517                          Error **errp);
 518
 519 /**
 520  * qio_channel_set_delay:
 521  * @ioc: the channel object
 522  * @enabled: the new flag state
 523  *
 524  * Controls whether the underlying transport is
 525  * permitted to delay writes in order to merge
 526  * small packets. If @enabled is true, then the
 527  * writes may be delayed in order to opportunistically
 528  * merge small packets into larger ones. If @enabled
 529  * is false, writes are dispatched immediately with
 530  * no delay.
 531  *
 532  * When @enabled is false, applications may wish to
 533  * use the qio_channel_set_cork() method to explicitly
 534  * control write merging.
 535  *
 536  * On channels which are backed by a socket, this
 537  * API corresponds to the inverse of TCP_NODELAY flag,
 538  * controlling whether the Nagle algorithm is active.
 539  *
 540  * This setting is merely a hint, so implementations are
 541  * free to ignore this without it being considered an
 542  * error.
 543  */
 544 void qio_channel_set_delay(QIOChannel *ioc,
 545                            bool enabled);
 546
 547 /**
 548  * qio_channel_set_cork:
 549  * @ioc: the channel object
 550  * @enabled: the new flag state
 551  *
 552  * Controls whether the underlying transport is
 553  * permitted to dispatch data that is written.
 554  * If @enabled is true, then any data written will
 555  * be queued in local buffers until @enabled is
 556  * set to false once again.
 557  *
 558  * This feature is typically used when the automatic
 559  * write coalescing facility is disabled via the
 560  * qio_channel_set_delay() method.
 561  *
 562  * On channels which are backed by a socket, this
 563  * API corresponds to the TCP_CORK flag.
 564  *
 565  * This setting is merely a hint, so implementations are
 566  * free to ignore this without it being considered an
 567  * error.
 568  */
 569 void qio_channel_set_cork(QIOChannel *ioc,
 570                           bool enabled);
 571
 572
 573 /**
 574  * qio_channel_seek:
 575  * @ioc: the channel object
 576  * @offset: the position to seek to, relative to @whence
 577  * @whence: one of the (POSIX) SEEK_* constants listed below
 578  * @errp: pointer to a NULL-initialized error object
 579  *
 580  * Moves the current I/O position within the channel
 581  * @ioc, to be @offset. The value of @offset is
 582  * interpreted relative to @whence:
 583  *
 584  * SEEK_SET - the position is set to @offset bytes
 585  * SEEK_CUR - the position is moved by @offset bytes
 586  * SEEK_END - the position is set to end of the file plus @offset bytes
 587  *
 588  * Not all implementations will support this facility,
 589  * so may report an error.
 590  *
 591  * Returns: the new position on success, (off_t)-1 on failure
 592  */
 593 off_t qio_channel_io_seek(QIOChannel *ioc,
 594                           off_t offset,
 595                           int whence,
 596                           Error **errp);
 597
 598
 599 /**
 600  * qio_channel_create_watch:
 601  * @ioc: the channel object
 602  * @condition: the I/O condition to monitor
 603  *
 604  * Create a new main loop source that is used to watch
 605  * for the I/O condition @condition. Typically the
 606  * qio_channel_add_watch() method would be used instead
 607  * of this, since it directly attaches a callback to
 608  * the source
 609  *
 610  * Returns: the new main loop source.
 611  */
 612 GSource *qio_channel_create_watch(QIOChannel *ioc,
 613                                   GIOCondition condition);
 614
 615 /**
 616  * qio_channel_add_watch:
 617  * @ioc: the channel object
 618  * @condition: the I/O condition to monitor
 619  * @func: callback to invoke when the source becomes ready
 620  * @user_data: opaque data to pass to @func
 621  * @notify: callback to free @user_data
 622  *
 623  * Create a new main loop source that is used to watch
 624  * for the I/O condition @condition. The callback @func
 625  * will be registered against the source, to be invoked
 626  * when the source becomes ready. The optional @user_data
 627  * will be passed to @func when it is invoked. The @notify
 628  * callback will be used to free @user_data when the
 629  * watch is deleted
 630  *
 631  * The returned source ID can be used with g_source_remove()
 632  * to remove and free the source when no longer required.
 633  * Alternatively the @func callback can return a FALSE
 634  * value.
 635  *
 636  * Returns: the source ID
 637  */
 638 guint qio_channel_add_watch(QIOChannel *ioc,
 639                             GIOCondition condition,
 640                             QIOChannelFunc func,
 641                             gpointer user_data,
 642                             GDestroyNotify notify);
 643
 644 /**
 645  * qio_channel_add_watch_full:
 646  * @ioc: the channel object
 647  * @condition: the I/O condition to monitor
 648  * @func: callback to invoke when the source becomes ready
 649  * @user_data: opaque data to pass to @func
 650  * @notify: callback to free @user_data
 651  * @context: the context to run the watch source
 652  *
 653  * Similar as qio_channel_add_watch(), but allows to specify context
 654  * to run the watch source.
 655  *
 656  * Returns: the source ID
 657  */
 658 guint qio_channel_add_watch_full(QIOChannel *ioc,
 659                                  GIOCondition condition,
 660                                  QIOChannelFunc func,
 661                                  gpointer user_data,
 662                                  GDestroyNotify notify,
 663                                  GMainContext *context);
 664
 665 /**
 666  * qio_channel_add_watch_source:
 667  * @ioc: the channel object
 668  * @condition: the I/O condition to monitor
 669  * @func: callback to invoke when the source becomes ready
 670  * @user_data: opaque data to pass to @func
 671  * @notify: callback to free @user_data
 672  * @context: gcontext to bind the source to
 673  *
 674  * Similar as qio_channel_add_watch(), but allows to specify context
 675  * to run the watch source, meanwhile return the GSource object
 676  * instead of tag ID, with the GSource referenced already.
 677  *
 678  * Note: callers is responsible to unref the source when not needed.
 679  *
 680  * Returns: the source pointer
 681  */
 682 GSource *qio_channel_add_watch_source(QIOChannel *ioc,
 683                                       GIOCondition condition,
 684                                       QIOChannelFunc func,
 685                                       gpointer user_data,
 686                                       GDestroyNotify notify,
 687                                       GMainContext *context);
 688
 689 /**
 690  * qio_channel_attach_aio_context:
 691  * @ioc: the channel object
 692  * @ctx: the #AioContext to set the handlers on
 693  *
 694  * Request that qio_channel_yield() sets I/O handlers on
 695  * the given #AioContext.  If @ctx is %NULL, qio_channel_yield()
 696  * uses QEMU's main thread event loop.
 697  *
 698  * You can move a #QIOChannel from one #AioContext to another even if
 699  * I/O handlers are set for a coroutine.  However, #QIOChannel provides
 700  * no synchronization between the calls to qio_channel_yield() and
 701  * qio_channel_attach_aio_context().
 702  *
 703  * Therefore you should first call qio_channel_detach_aio_context()
 704  * to ensure that the coroutine is not entered concurrently.  Then,
 705  * while the coroutine has yielded, call qio_channel_attach_aio_context(),
 706  * and then aio_co_schedule() to place the coroutine on the new
 707  * #AioContext.  The calls to qio_channel_detach_aio_context()
 708  * and qio_channel_attach_aio_context() should be protected with
 709  * aio_context_acquire() and aio_context_release().
 710  */
 711 void qio_channel_attach_aio_context(QIOChannel *ioc,
 712                                     AioContext *ctx);
 713
 714 /**
 715  * qio_channel_detach_aio_context:
 716  * @ioc: the channel object
 717  *
 718  * Disable any I/O handlers set by qio_channel_yield().  With the
 719  * help of aio_co_schedule(), this allows moving a coroutine that was
 720  * paused by qio_channel_yield() to another context.
 721  */
 722 void qio_channel_detach_aio_context(QIOChannel *ioc);
 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_wait:
 745  * @ioc: the channel object
 746  * @condition: the I/O condition to wait for
 747  *
 748  * Block execution from the current thread until
 749  * the condition indicated by @condition becomes
 750  * available.
 751  *
 752  * This will enter a nested event loop to perform
 753  * the wait.
 754  */
 755 void qio_channel_wait(QIOChannel *ioc,
 756                       GIOCondition condition);
 757
 758 /**
 759  * qio_channel_set_aio_fd_handler:
 760  * @ioc: the channel object
 761  * @ctx: the AioContext to set the handlers on
 762  * @io_read: the read handler
 763  * @io_write: the write handler
 764  * @opaque: the opaque value passed to the handler
 765  *
 766  * This is used internally by qio_channel_yield().  It can
 767  * be used by channel implementations to forward the handlers
 768  * to another channel (e.g. from #QIOChannelTLS to the
 769  * underlying socket).
 770  */
 771 void qio_channel_set_aio_fd_handler(QIOChannel *ioc,
 772                                     AioContext *ctx,
 773                                     IOHandler *io_read,
 774                                     IOHandler *io_write,
 775                                     void *opaque);
 776
 777 #endif /* QIO_CHANNEL_H */