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