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 "qemu-common.h"
  25 #include "qom/object.h"
  26
  27 #define TYPE_QIO_CHANNEL "qio-channel"
  28 #define QIO_CHANNEL(obj)                                    \
  29     OBJECT_CHECK(QIOChannel, (obj), TYPE_QIO_CHANNEL)
  30 #define QIO_CHANNEL_CLASS(klass)                                    \
  31     OBJECT_CLASS_CHECK(QIOChannelClass, klass, TYPE_QIO_CHANNEL)
  32 #define QIO_CHANNEL_GET_CLASS(obj)                                  \
  33     OBJECT_GET_CLASS(QIOChannelClass, obj, TYPE_QIO_CHANNEL)
  34
  35 typedef struct QIOChannel QIOChannel;
  36 typedef struct QIOChannelClass QIOChannelClass;
  37
  38 #define QIO_CHANNEL_ERR_BLOCK -2
  39
  40 typedef enum QIOChannelFeature QIOChannelFeature;
  41
  42 enum QIOChannelFeature {
  43     QIO_CHANNEL_FEATURE_FD_PASS,
  44     QIO_CHANNEL_FEATURE_SHUTDOWN,
  45     QIO_CHANNEL_FEATURE_LISTEN,
  46 };
  47
  48
  49 typedef enum QIOChannelShutdown QIOChannelShutdown;
  50
  51 enum QIOChannelShutdown {
  52     QIO_CHANNEL_SHUTDOWN_BOTH,
  53     QIO_CHANNEL_SHUTDOWN_READ,
  54     QIO_CHANNEL_SHUTDOWN_WRITE,
  55 };
  56
  57 typedef gboolean (*QIOChannelFunc)(QIOChannel *ioc,
  58                                    GIOCondition condition,
  59                                    gpointer data);
  60
  61 /**
  62  * QIOChannel:
  63  *
  64  * The QIOChannel defines the core API for a generic I/O channel
  65  * class hierarchy. It is inspired by GIOChannel, but has the
  66  * following differences
  67  *
  68  *  - Use QOM to properly support arbitrary subclassing
  69  *  - Support use of iovecs for efficient I/O with multiple blocks
  70  *  - None of the character set translation, binary data exclusively
  71  *  - Direct support for QEMU Error object reporting
  72  *  - File descriptor passing
  73  *
  74  * This base class is abstract so cannot be instantiated. There
  75  * will be subclasses for dealing with sockets, files, and higher
  76  * level protocols such as TLS, WebSocket, etc.
  77  */
  78
  79 struct QIOChannel {
  80     Object parent;
  81     unsigned int features; /* bitmask of QIOChannelFeatures */
  82     char *name;
  83 #ifdef _WIN32
  84     HANDLE event; /* For use with GSource on Win32 */
  85 #endif
  86 };
  87
  88 /**
  89  * QIOChannelClass:
  90  *
  91  * This class defines the contract that all subclasses
  92  * must follow to provide specific channel implementations.
  93  * The first five callbacks are mandatory to support, others
  94  * provide additional optional features.
  95  *
  96  * Consult the corresponding public API docs for a description
  97  * of the semantics of each callback
  98  */
  99 struct QIOChannelClass {
 100     ObjectClass parent;
 101
 102     /* Mandatory callbacks */
 103     ssize_t (*io_writev)(QIOChannel *ioc,
 104                          const struct iovec *iov,
 105                          size_t niov,
 106                          int *fds,
 107                          size_t nfds,
 108                          Error **errp);
 109     ssize_t (*io_readv)(QIOChannel *ioc,
 110                         const struct iovec *iov,
 111                         size_t niov,
 112                         int **fds,
 113                         size_t *nfds,
 114                         Error **errp);
 115     int (*io_close)(QIOChannel *ioc,
 116                     Error **errp);
 117     GSource * (*io_create_watch)(QIOChannel *ioc,
 118                                  GIOCondition condition);
 119     int (*io_set_blocking)(QIOChannel *ioc,
 120                            bool enabled,
 121                            Error **errp);
 122
 123     /* Optional callbacks */
 124     int (*io_shutdown)(QIOChannel *ioc,
 125                        QIOChannelShutdown how,
 126                        Error **errp);
 127     void (*io_set_cork)(QIOChannel *ioc,
 128                         bool enabled);
 129     void (*io_set_delay)(QIOChannel *ioc,
 130                          bool enabled);
 131     off_t (*io_seek)(QIOChannel *ioc,
 132                      off_t offset,
 133                      int whence,
 134                      Error **errp);
 135 };
 136
 137 /* General I/O handling functions */
 138
 139 /**
 140  * qio_channel_has_feature:
 141  * @ioc: the channel object
 142  * @feature: the feature to check support of
 143  *
 144  * Determine whether the channel implementation supports
 145  * the optional feature named in @feature.
 146  *
 147  * Returns: true if supported, false otherwise.
 148  */
 149 bool qio_channel_has_feature(QIOChannel *ioc,
 150                              QIOChannelFeature feature);
 151
 152 /**
 153  * qio_channel_set_feature:
 154  * @ioc: the channel object
 155  * @feature: the feature to set support for
 156  *
 157  * Add channel support for the feature named in @feature.
 158  */
 159 void qio_channel_set_feature(QIOChannel *ioc,
 160                              QIOChannelFeature feature);
 161
 162 /**
 163  * qio_channel_set_name:
 164  * @ioc: the channel object
 165  * @name: the name of the channel
 166  *
 167  * Sets the name of the channel, which serves as an aid
 168  * to debugging. The name is used when creating GSource
 169  * watches for this channel.
 170  */
 171 void qio_channel_set_name(QIOChannel *ioc,
 172                           const char *name);
 173
 174 /**
 175  * qio_channel_readv_full:
 176  * @ioc: the channel object
 177  * @iov: the array of memory regions to read data into
 178  * @niov: the length of the @iov array
 179  * @fds: pointer to an array that will received file handles
 180  * @nfds: pointer filled with number of elements in @fds on return
 181  * @errp: pointer to a NULL-initialized error object
 182  *
 183  * Read data from the IO channel, storing it in the
 184  * memory regions referenced by @iov. Each element
 185  * in the @iov will be fully populated with data
 186  * before the next one is used. The @niov parameter
 187  * specifies the total number of elements in @iov.
 188  *
 189  * It is not required for all @iov to be filled with
 190  * data. If the channel is in blocking mode, at least
 191  * one byte of data will be read, but no more is
 192  * guaranteed. If the channel is non-blocking and no
 193  * data is available, it will return QIO_CHANNEL_ERR_BLOCK
 194  *
 195  * If the channel has passed any file descriptors,
 196  * the @fds array pointer will be allocated and
 197  * the elements filled with the received file
 198  * descriptors. The @nfds pointer will be updated
 199  * to indicate the size of the @fds array that
 200  * was allocated. It is the callers responsibility
 201  * to call close() on each file descriptor and to
 202  * call g_free() on the array pointer in @fds.
 203  *
 204  * It is an error to pass a non-NULL @fds parameter
 205  * unless qio_channel_has_feature() returns a true
 206  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
 207  *
 208  * Returns: the number of bytes read, or -1 on error,
 209  * or QIO_CHANNEL_ERR_BLOCK if no data is available
 210  * and the channel is non-blocking
 211  */
 212 ssize_t qio_channel_readv_full(QIOChannel *ioc,
 213                                const struct iovec *iov,
 214                                size_t niov,
 215                                int **fds,
 216                                size_t *nfds,
 217                                Error **errp);
 218
 219
 220 /**
 221  * qio_channel_writev_full:
 222  * @ioc: the channel object
 223  * @iov: the array of memory regions to write data from
 224  * @niov: the length of the @iov array
 225  * @fds: an array of file handles to send
 226  * @nfds: number of file handles in @fds
 227  * @errp: pointer to a NULL-initialized error object
 228  *
 229  * Write data to the IO channel, reading it from the
 230  * memory regions referenced by @iov. Each element
 231  * in the @iov will be fully sent, before the next
 232  * one is used. The @niov parameter specifies the
 233  * total number of elements in @iov.
 234  *
 235  * It is not required for all @iov data to be fully
 236  * sent. If the channel is in blocking mode, at least
 237  * one byte of data will be sent, but no more is
 238  * guaranteed. If the channel is non-blocking and no
 239  * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK
 240  *
 241  * If there are file descriptors to send, the @fds
 242  * array should be non-NULL and provide the handles.
 243  * All file descriptors will be sent if at least one
 244  * byte of data was sent.
 245  *
 246  * It is an error to pass a non-NULL @fds parameter
 247  * unless qio_channel_has_feature() returns a true
 248  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
 249  *
 250  * Returns: the number of bytes sent, or -1 on error,
 251  * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent
 252  * and the channel is non-blocking
 253  */
 254 ssize_t qio_channel_writev_full(QIOChannel *ioc,
 255                                 const struct iovec *iov,
 256                                 size_t niov,
 257                                 int *fds,
 258                                 size_t nfds,
 259                                 Error **errp);
 260
 261 /**
 262  * qio_channel_readv:
 263  * @ioc: the channel object
 264  * @iov: the array of memory regions to read data into
 265  * @niov: the length of the @iov array
 266  * @errp: pointer to a NULL-initialized error object
 267  *
 268  * Behaves as qio_channel_readv_full() but does not support
 269  * receiving of file handles.
 270  */
 271 ssize_t qio_channel_readv(QIOChannel *ioc,
 272                           const struct iovec *iov,
 273                           size_t niov,
 274                           Error **errp);
 275
 276 /**
 277  * qio_channel_writev:
 278  * @ioc: the channel object
 279  * @iov: the array of memory regions to write data from
 280  * @niov: the length of the @iov array
 281  * @errp: pointer to a NULL-initialized error object
 282  *
 283  * Behaves as qio_channel_writev_full() but does not support
 284  * sending of file handles.
 285  */
 286 ssize_t qio_channel_writev(QIOChannel *ioc,
 287                            const struct iovec *iov,
 288                            size_t niov,
 289                            Error **errp);
 290
 291 /**
 292  * qio_channel_readv:
 293  * @ioc: the channel object
 294  * @buf: the memory region to read data into
 295  * @buflen: the length of @buf
 296  * @errp: pointer to a NULL-initialized error object
 297  *
 298  * Behaves as qio_channel_readv_full() but does not support
 299  * receiving of file handles, and only supports reading into
 300  * a single memory region.
 301  */
 302 ssize_t qio_channel_read(QIOChannel *ioc,
 303                          char *buf,
 304                          size_t buflen,
 305                          Error **errp);
 306
 307 /**
 308  * qio_channel_writev:
 309  * @ioc: the channel object
 310  * @buf: the memory regions to send data from
 311  * @buflen: the length of @buf
 312  * @errp: pointer to a NULL-initialized error object
 313  *
 314  * Behaves as qio_channel_writev_full() but does not support
 315  * sending of file handles, and only supports writing from a
 316  * single memory region.
 317  */
 318 ssize_t qio_channel_write(QIOChannel *ioc,
 319                           const char *buf,
 320                           size_t buflen,
 321                           Error **errp);
 322
 323 /**
 324  * qio_channel_set_blocking:
 325  * @ioc: the channel object
 326  * @enabled: the blocking flag state
 327  * @errp: pointer to a NULL-initialized error object
 328  *
 329  * If @enabled is true, then the channel is put into
 330  * blocking mode, otherwise it will be non-blocking.
 331  *
 332  * In non-blocking mode, read/write operations may
 333  * return QIO_CHANNEL_ERR_BLOCK if they would otherwise
 334  * block on I/O
 335  */
 336 int qio_channel_set_blocking(QIOChannel *ioc,
 337                              bool enabled,
 338                              Error **errp);
 339
 340 /**
 341  * qio_channel_close:
 342  * @ioc: the channel object
 343  * @errp: pointer to a NULL-initialized error object
 344  *
 345  * Close the channel, flushing any pending I/O
 346  *
 347  * Returns: 0 on success, -1 on error
 348  */
 349 int qio_channel_close(QIOChannel *ioc,
 350                       Error **errp);
 351
 352 /**
 353  * qio_channel_shutdown:
 354  * @ioc: the channel object
 355  * @how: the direction to shutdown
 356  * @errp: pointer to a NULL-initialized error object
 357  *
 358  * Shutdowns transmission and/or receiving of data
 359  * without closing the underlying transport.
 360  *
 361  * Not all implementations will support this facility,
 362  * so may report an error. To avoid errors, the
 363  * caller may check for the feature flag
 364  * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling
 365  * this method.
 366  *
 367  * Returns: 0 on success, -1 on error
 368  */
 369 int qio_channel_shutdown(QIOChannel *ioc,
 370                          QIOChannelShutdown how,
 371                          Error **errp);
 372
 373 /**
 374  * qio_channel_set_delay:
 375  * @ioc: the channel object
 376  * @enabled: the new flag state
 377  *
 378  * Controls whether the underlying transport is
 379  * permitted to delay writes in order to merge
 380  * small packets. If @enabled is true, then the
 381  * writes may be delayed in order to opportunistically
 382  * merge small packets into larger ones. If @enabled
 383  * is false, writes are dispatched immediately with
 384  * no delay.
 385  *
 386  * When @enabled is false, applications may wish to
 387  * use the qio_channel_set_cork() method to explicitly
 388  * control write merging.
 389  *
 390  * On channels which are backed by a socket, this
 391  * API corresponds to the inverse of TCP_NODELAY flag,
 392  * controlling whether the Nagle algorithm is active.
 393  *
 394  * This setting is merely a hint, so implementations are
 395  * free to ignore this without it being considered an
 396  * error.
 397  */
 398 void qio_channel_set_delay(QIOChannel *ioc,
 399                            bool enabled);
 400
 401 /**
 402  * qio_channel_set_cork:
 403  * @ioc: the channel object
 404  * @enabled: the new flag state
 405  *
 406  * Controls whether the underlying transport is
 407  * permitted to dispatch data that is written.
 408  * If @enabled is true, then any data written will
 409  * be queued in local buffers until @enabled is
 410  * set to false once again.
 411  *
 412  * This feature is typically used when the automatic
 413  * write coalescing facility is disabled via the
 414  * qio_channel_set_delay() method.
 415  *
 416  * On channels which are backed by a socket, this
 417  * API corresponds to the TCP_CORK flag.
 418  *
 419  * This setting is merely a hint, so implementations are
 420  * free to ignore this without it being considered an
 421  * error.
 422  */
 423 void qio_channel_set_cork(QIOChannel *ioc,
 424                           bool enabled);
 425
 426
 427 /**
 428  * qio_channel_seek:
 429  * @ioc: the channel object
 430  * @offset: the position to seek to, relative to @whence
 431  * @whence: one of the (POSIX) SEEK_* constants listed below
 432  * @errp: pointer to a NULL-initialized error object
 433  *
 434  * Moves the current I/O position within the channel
 435  * @ioc, to be @offset. The value of @offset is
 436  * interpreted relative to @whence:
 437  *
 438  * SEEK_SET - the position is set to @offset bytes
 439  * SEEK_CUR - the position is moved by @offset bytes
 440  * SEEK_END - the position is set to end of the file plus @offset bytes
 441  *
 442  * Not all implementations will support this facility,
 443  * so may report an error.
 444  *
 445  * Returns: the new position on success, (off_t)-1 on failure
 446  */
 447 off_t qio_channel_io_seek(QIOChannel *ioc,
 448                           off_t offset,
 449                           int whence,
 450                           Error **errp);
 451
 452
 453 /**
 454  * qio_channel_create_watch:
 455  * @ioc: the channel object
 456  * @condition: the I/O condition to monitor
 457  *
 458  * Create a new main loop source that is used to watch
 459  * for the I/O condition @condition. Typically the
 460  * qio_channel_add_watch() method would be used instead
 461  * of this, since it directly attaches a callback to
 462  * the source
 463  *
 464  * Returns: the new main loop source.
 465  */
 466 GSource *qio_channel_create_watch(QIOChannel *ioc,
 467                                   GIOCondition condition);
 468
 469 /**
 470  * qio_channel_add_watch:
 471  * @ioc: the channel object
 472  * @condition: the I/O condition to monitor
 473  * @func: callback to invoke when the source becomes ready
 474  * @user_data: opaque data to pass to @func
 475  * @notify: callback to free @user_data
 476  *
 477  * Create a new main loop source that is used to watch
 478  * for the I/O condition @condition. The callback @func
 479  * will be registered against the source, to be invoked
 480  * when the source becomes ready. The optional @user_data
 481  * will be passed to @func when it is invoked. The @notify
 482  * callback will be used to free @user_data when the
 483  * watch is deleted
 484  *
 485  * The returned source ID can be used with g_source_remove()
 486  * to remove and free the source when no longer required.
 487  * Alternatively the @func callback can return a FALSE
 488  * value.
 489  *
 490  * Returns: the source ID
 491  */
 492 guint qio_channel_add_watch(QIOChannel *ioc,
 493                             GIOCondition condition,
 494                             QIOChannelFunc func,
 495                             gpointer user_data,
 496                             GDestroyNotify notify);
 497
 498
 499 /**
 500  * qio_channel_yield:
 501  * @ioc: the channel object
 502  * @condition: the I/O condition to wait for
 503  *
 504  * Yields execution from the current coroutine until
 505  * the condition indicated by @condition becomes
 506  * available.
 507  *
 508  * This must only be called from coroutine context
 509  */
 510 void qio_channel_yield(QIOChannel *ioc,
 511                        GIOCondition condition);
 512
 513 /**
 514  * qio_channel_wait:
 515  * @ioc: the channel object
 516  * @condition: the I/O condition to wait for
 517  *
 518  * Block execution from the current thread until
 519  * the condition indicated by @condition becomes
 520  * available.
 521  *
 522  * This will enter a nested event loop to perform
 523  * the wait.
 524  */
 525 void qio_channel_wait(QIOChannel *ioc,
 526                       GIOCondition condition);
 527
 528 #endif /* QIO_CHANNEL_H */