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  = (1 << 0),
  44     QIO_CHANNEL_FEATURE_SHUTDOWN = (1 << 1),
  45     QIO_CHANNEL_FEATURE_LISTEN   = (1 << 2),
  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 #ifdef _WIN32
  83     HANDLE event; /* For use with GSource on Win32 */
  84 #endif
  85 };
  86
  87 /**
  88  * QIOChannelClass:
  89  *
  90  * This class defines the contract that all subclasses
  91  * must follow to provide specific channel implementations.
  92  * The first five callbacks are mandatory to support, others
  93  * provide additional optional features.
  94  *
  95  * Consult the corresponding public API docs for a description
  96  * of the semantics of each callback
  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 };
 135
 136 /* General I/O handling functions */
 137
 138 /**
 139  * qio_channel_has_feature:
 140  * @ioc: the channel object
 141  * @feature: the feature to check support of
 142  *
 143  * Determine whether the channel implementation supports
 144  * the optional feature named in @feature.
 145  *
 146  * Returns: true if supported, false otherwise.
 147  */
 148 bool qio_channel_has_feature(QIOChannel *ioc,
 149                              QIOChannelFeature feature);
 150
 151 /**
 152  * qio_channel_readv_full:
 153  * @ioc: the channel object
 154  * @iov: the array of memory regions to read data into
 155  * @niov: the length of the @iov array
 156  * @fds: pointer to an array that will received file handles
 157  * @nfds: pointer filled with number of elements in @fds on return
 158  * @errp: pointer to a NULL-initialized error object
 159  *
 160  * Read data from the IO channel, storing it in the
 161  * memory regions referenced by @iov. Each element
 162  * in the @iov will be fully populated with data
 163  * before the next one is used. The @niov parameter
 164  * specifies the total number of elements in @iov.
 165  *
 166  * It is not required for all @iov to be filled with
 167  * data. If the channel is in blocking mode, at least
 168  * one byte of data will be read, but no more is
 169  * guaranteed. If the channel is non-blocking and no
 170  * data is available, it will return QIO_CHANNEL_ERR_BLOCK
 171  *
 172  * If the channel has passed any file descriptors,
 173  * the @fds array pointer will be allocated and
 174  * the elements filled with the received file
 175  * descriptors. The @nfds pointer will be updated
 176  * to indicate the size of the @fds array that
 177  * was allocated. It is the callers responsibility
 178  * to call close() on each file descriptor and to
 179  * call g_free() on the array pointer in @fds.
 180  *
 181  * It is an error to pass a non-NULL @fds parameter
 182  * unless qio_channel_has_feature() returns a true
 183  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
 184  *
 185  * Returns: the number of bytes read, or -1 on error,
 186  * or QIO_CHANNEL_ERR_BLOCK if no data is available
 187  * and the channel is non-blocking
 188  */
 189 ssize_t qio_channel_readv_full(QIOChannel *ioc,
 190                                const struct iovec *iov,
 191                                size_t niov,
 192                                int **fds,
 193                                size_t *nfds,
 194                                Error **errp);
 195
 196
 197 /**
 198  * qio_channel_writev_full:
 199  * @ioc: the channel object
 200  * @iov: the array of memory regions to write data from
 201  * @niov: the length of the @iov array
 202  * @fds: an array of file handles to send
 203  * @nfds: number of file handles in @fds
 204  * @errp: pointer to a NULL-initialized error object
 205  *
 206  * Write data to the IO channel, reading it from the
 207  * memory regions referenced by @iov. Each element
 208  * in the @iov will be fully sent, before the next
 209  * one is used. The @niov parameter specifies the
 210  * total number of elements in @iov.
 211  *
 212  * It is not required for all @iov data to be fully
 213  * sent. If the channel is in blocking mode, at least
 214  * one byte of data will be sent, but no more is
 215  * guaranteed. If the channel is non-blocking and no
 216  * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK
 217  *
 218  * If there are file descriptors to send, the @fds
 219  * array should be non-NULL and provide the handles.
 220  * All file descriptors will be sent if at least one
 221  * byte of data was sent.
 222  *
 223  * It is an error to pass a non-NULL @fds parameter
 224  * unless qio_channel_has_feature() returns a true
 225  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
 226  *
 227  * Returns: the number of bytes sent, or -1 on error,
 228  * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent
 229  * and the channel is non-blocking
 230  */
 231 ssize_t qio_channel_writev_full(QIOChannel *ioc,
 232                                 const struct iovec *iov,
 233                                 size_t niov,
 234                                 int *fds,
 235                                 size_t nfds,
 236                                 Error **errp);
 237
 238 /**
 239  * qio_channel_readv:
 240  * @ioc: the channel object
 241  * @iov: the array of memory regions to read data into
 242  * @niov: the length of the @iov array
 243  * @errp: pointer to a NULL-initialized error object
 244  *
 245  * Behaves as qio_channel_readv_full() but does not support
 246  * receiving of file handles.
 247  */
 248 ssize_t qio_channel_readv(QIOChannel *ioc,
 249                           const struct iovec *iov,
 250                           size_t niov,
 251                           Error **errp);
 252
 253 /**
 254  * qio_channel_writev:
 255  * @ioc: the channel object
 256  * @iov: the array of memory regions to write data from
 257  * @niov: the length of the @iov array
 258  * @errp: pointer to a NULL-initialized error object
 259  *
 260  * Behaves as qio_channel_writev_full() but does not support
 261  * sending of file handles.
 262  */
 263 ssize_t qio_channel_writev(QIOChannel *ioc,
 264                            const struct iovec *iov,
 265                            size_t niov,
 266                            Error **errp);
 267
 268 /**
 269  * qio_channel_readv:
 270  * @ioc: the channel object
 271  * @buf: the memory region to read data into
 272  * @buflen: the length of @buf
 273  * @errp: pointer to a NULL-initialized error object
 274  *
 275  * Behaves as qio_channel_readv_full() but does not support
 276  * receiving of file handles, and only supports reading into
 277  * a single memory region.
 278  */
 279 ssize_t qio_channel_read(QIOChannel *ioc,
 280                          char *buf,
 281                          size_t buflen,
 282                          Error **errp);
 283
 284 /**
 285  * qio_channel_writev:
 286  * @ioc: the channel object
 287  * @buf: the memory regions to send data from
 288  * @buflen: the length of @buf
 289  * @errp: pointer to a NULL-initialized error object
 290  *
 291  * Behaves as qio_channel_writev_full() but does not support
 292  * sending of file handles, and only supports writing from a
 293  * single memory region.
 294  */
 295 ssize_t qio_channel_write(QIOChannel *ioc,
 296                           const char *buf,
 297                           size_t buflen,
 298                           Error **errp);
 299
 300 /**
 301  * qio_channel_set_blocking:
 302  * @ioc: the channel object
 303  * @enabled: the blocking flag state
 304  * @errp: pointer to a NULL-initialized error object
 305  *
 306  * If @enabled is true, then the channel is put into
 307  * blocking mode, otherwise it will be non-blocking.
 308  *
 309  * In non-blocking mode, read/write operations may
 310  * return QIO_CHANNEL_ERR_BLOCK if they would otherwise
 311  * block on I/O
 312  */
 313 int qio_channel_set_blocking(QIOChannel *ioc,
 314                              bool enabled,
 315                              Error **errp);
 316
 317 /**
 318  * qio_channel_close:
 319  * @ioc: the channel object
 320  * @errp: pointer to a NULL-initialized error object
 321  *
 322  * Close the channel, flushing any pending I/O
 323  *
 324  * Returns: 0 on success, -1 on error
 325  */
 326 int qio_channel_close(QIOChannel *ioc,
 327                       Error **errp);
 328
 329 /**
 330  * qio_channel_shutdown:
 331  * @ioc: the channel object
 332  * @how: the direction to shutdown
 333  * @errp: pointer to a NULL-initialized error object
 334  *
 335  * Shutdowns transmission and/or receiving of data
 336  * without closing the underlying transport.
 337  *
 338  * Not all implementations will support this facility,
 339  * so may report an error. To avoid errors, the
 340  * caller may check for the feature flag
 341  * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling
 342  * this method.
 343  *
 344  * Returns: 0 on success, -1 on error
 345  */
 346 int qio_channel_shutdown(QIOChannel *ioc,
 347                          QIOChannelShutdown how,
 348                          Error **errp);
 349
 350 /**
 351  * qio_channel_set_delay:
 352  * @ioc: the channel object
 353  * @enabled: the new flag state
 354  *
 355  * Controls whether the underlying transport is
 356  * permitted to delay writes in order to merge
 357  * small packets. If @enabled is true, then the
 358  * writes may be delayed in order to opportunistically
 359  * merge small packets into larger ones. If @enabled
 360  * is false, writes are dispatched immediately with
 361  * no delay.
 362  *
 363  * When @enabled is false, applications may wish to
 364  * use the qio_channel_set_cork() method to explicitly
 365  * control write merging.
 366  *
 367  * On channels which are backed by a socket, this
 368  * API corresponds to the inverse of TCP_NODELAY flag,
 369  * controlling whether the Nagle algorithm is active.
 370  *
 371  * This setting is merely a hint, so implementations are
 372  * free to ignore this without it being considered an
 373  * error.
 374  */
 375 void qio_channel_set_delay(QIOChannel *ioc,
 376                            bool enabled);
 377
 378 /**
 379  * qio_channel_set_cork:
 380  * @ioc: the channel object
 381  * @enabled: the new flag state
 382  *
 383  * Controls whether the underlying transport is
 384  * permitted to dispatch data that is written.
 385  * If @enabled is true, then any data written will
 386  * be queued in local buffers until @enabled is
 387  * set to false once again.
 388  *
 389  * This feature is typically used when the automatic
 390  * write coalescing facility is disabled via the
 391  * qio_channel_set_delay() method.
 392  *
 393  * On channels which are backed by a socket, this
 394  * API corresponds to the TCP_CORK flag.
 395  *
 396  * This setting is merely a hint, so implementations are
 397  * free to ignore this without it being considered an
 398  * error.
 399  */
 400 void qio_channel_set_cork(QIOChannel *ioc,
 401                           bool enabled);
 402
 403
 404 /**
 405  * qio_channel_seek:
 406  * @ioc: the channel object
 407  * @offset: the position to seek to, relative to @whence
 408  * @whence: one of the (POSIX) SEEK_* constants listed below
 409  * @errp: pointer to a NULL-initialized error object
 410  *
 411  * Moves the current I/O position within the channel
 412  * @ioc, to be @offset. The value of @offset is
 413  * interpreted relative to @whence:
 414  *
 415  * SEEK_SET - the position is set to @offset bytes
 416  * SEEK_CUR - the position is moved by @offset bytes
 417  * SEEK_END - the position is set to end of the file plus @offset bytes
 418  *
 419  * Not all implementations will support this facility,
 420  * so may report an error.
 421  *
 422  * Returns: the new position on success, (off_t)-1 on failure
 423  */
 424 off_t qio_channel_io_seek(QIOChannel *ioc,
 425                           off_t offset,
 426                           int whence,
 427                           Error **errp);
 428
 429
 430 /**
 431  * qio_channel_create_watch:
 432  * @ioc: the channel object
 433  * @condition: the I/O condition to monitor
 434  *
 435  * Create a new main loop source that is used to watch
 436  * for the I/O condition @condition. Typically the
 437  * qio_channel_add_watch() method would be used instead
 438  * of this, since it directly attaches a callback to
 439  * the source
 440  *
 441  * Returns: the new main loop source.
 442  */
 443 GSource *qio_channel_create_watch(QIOChannel *ioc,
 444                                   GIOCondition condition);
 445
 446 /**
 447  * qio_channel_add_watch:
 448  * @ioc: the channel object
 449  * @condition: the I/O condition to monitor
 450  * @func: callback to invoke when the source becomes ready
 451  * @user_data: opaque data to pass to @func
 452  * @notify: callback to free @user_data
 453  *
 454  * Create a new main loop source that is used to watch
 455  * for the I/O condition @condition. The callback @func
 456  * will be registered against the source, to be invoked
 457  * when the source becomes ready. The optional @user_data
 458  * will be passed to @func when it is invoked. The @notify
 459  * callback will be used to free @user_data when the
 460  * watch is deleted
 461  *
 462  * The returned source ID can be used with g_source_remove()
 463  * to remove and free the source when no longer required.
 464  * Alternatively the @func callback can return a FALSE
 465  * value.
 466  *
 467  * Returns: the source ID
 468  */
 469 guint qio_channel_add_watch(QIOChannel *ioc,
 470                             GIOCondition condition,
 471                             QIOChannelFunc func,
 472                             gpointer user_data,
 473                             GDestroyNotify notify);
 474
 475
 476 /**
 477  * qio_channel_yield:
 478  * @ioc: the channel object
 479  * @condition: the I/O condition to wait for
 480  *
 481  * Yields execution from the current coroutine until
 482  * the condition indicated by @condition becomes
 483  * available.
 484  *
 485  * This must only be called from coroutine context
 486  */
 487 void qio_channel_yield(QIOChannel *ioc,
 488                        GIOCondition condition);
 489
 490 /**
 491  * qio_channel_wait:
 492  * @ioc: the channel object
 493  * @condition: the I/O condition to wait for
 494  *
 495  * Block execution from the current thread until
 496  * the condition indicated by @condition becomes
 497  * available.
 498  *
 499  * This will enter a nested event loop to perform
 500  * the wait.
 501  */
 502 void qio_channel_wait(QIOChannel *ioc,
 503                       GIOCondition condition);
 504
 505 #endif /* QIO_CHANNEL_H */