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