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