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