| /* |
| * QEMU I/O channels |
| * |
| * Copyright (c) 2015 Red Hat, Inc. |
| * |
| * This library is free software; you can redistribute it and/or |
| * modify it under the terms of the GNU Lesser General Public |
| * License as published by the Free Software Foundation; either |
| * version 2.1 of the License, or (at your option) any later version. |
| * |
| * This library is distributed in the hope that it will be useful, |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| * Lesser General Public License for more details. |
| * |
| * You should have received a copy of the GNU Lesser General Public |
| * License along with this library; if not, see <http://www.gnu.org/licenses/>. |
| * |
| */ |
| |
| #ifndef QIO_CHANNEL_H |
| #define QIO_CHANNEL_H |
| |
| #include "qom/object.h" |
| #include "qemu/coroutine-core.h" |
| #include "block/aio.h" |
| |
| #define TYPE_QIO_CHANNEL "qio-channel" |
| OBJECT_DECLARE_TYPE(QIOChannel, QIOChannelClass, |
| QIO_CHANNEL) |
| |
| |
| #define QIO_CHANNEL_ERR_BLOCK -2 |
| |
| #define QIO_CHANNEL_WRITE_FLAG_ZERO_COPY 0x1 |
| |
| #define QIO_CHANNEL_READ_FLAG_MSG_PEEK 0x1 |
| |
| typedef enum QIOChannelFeature QIOChannelFeature; |
| |
| enum QIOChannelFeature { |
| QIO_CHANNEL_FEATURE_FD_PASS, |
| QIO_CHANNEL_FEATURE_SHUTDOWN, |
| QIO_CHANNEL_FEATURE_LISTEN, |
| QIO_CHANNEL_FEATURE_WRITE_ZERO_COPY, |
| QIO_CHANNEL_FEATURE_READ_MSG_PEEK, |
| QIO_CHANNEL_FEATURE_SEEKABLE, |
| }; |
| |
| |
| typedef enum QIOChannelShutdown QIOChannelShutdown; |
| |
| enum QIOChannelShutdown { |
| QIO_CHANNEL_SHUTDOWN_READ = 1, |
| QIO_CHANNEL_SHUTDOWN_WRITE = 2, |
| QIO_CHANNEL_SHUTDOWN_BOTH = 3, |
| }; |
| |
| typedef gboolean (*QIOChannelFunc)(QIOChannel *ioc, |
| GIOCondition condition, |
| gpointer data); |
| |
| /** |
| * QIOChannel: |
| * |
| * The QIOChannel defines the core API for a generic I/O channel |
| * class hierarchy. It is inspired by GIOChannel, but has the |
| * following differences |
| * |
| * - Use QOM to properly support arbitrary subclassing |
| * - Support use of iovecs for efficient I/O with multiple blocks |
| * - None of the character set translation, binary data exclusively |
| * - Direct support for QEMU Error object reporting |
| * - File descriptor passing |
| * |
| * This base class is abstract so cannot be instantiated. There |
| * will be subclasses for dealing with sockets, files, and higher |
| * level protocols such as TLS, WebSocket, etc. |
| */ |
| |
| struct QIOChannel { |
| Object parent; |
| unsigned int features; /* bitmask of QIOChannelFeatures */ |
| char *name; |
| AioContext *read_ctx; |
| Coroutine *read_coroutine; |
| AioContext *write_ctx; |
| Coroutine *write_coroutine; |
| bool follow_coroutine_ctx; |
| #ifdef _WIN32 |
| HANDLE event; /* For use with GSource on Win32 */ |
| #endif |
| }; |
| |
| /** |
| * QIOChannelClass: |
| * |
| * This class defines the contract that all subclasses |
| * must follow to provide specific channel implementations. |
| * The first five callbacks are mandatory to support, others |
| * provide additional optional features. |
| * |
| * Consult the corresponding public API docs for a description |
| * of the semantics of each callback. io_shutdown in particular |
| * must be thread-safe, terminate quickly and must not block. |
| */ |
| struct QIOChannelClass { |
| ObjectClass parent; |
| |
| /* Mandatory callbacks */ |
| ssize_t (*io_writev)(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| int *fds, |
| size_t nfds, |
| int flags, |
| Error **errp); |
| ssize_t (*io_readv)(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| int **fds, |
| size_t *nfds, |
| int flags, |
| Error **errp); |
| int (*io_close)(QIOChannel *ioc, |
| Error **errp); |
| GSource * (*io_create_watch)(QIOChannel *ioc, |
| GIOCondition condition); |
| int (*io_set_blocking)(QIOChannel *ioc, |
| bool enabled, |
| Error **errp); |
| |
| /* Optional callbacks */ |
| ssize_t (*io_pwritev)(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| off_t offset, |
| Error **errp); |
| ssize_t (*io_preadv)(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| off_t offset, |
| Error **errp); |
| int (*io_shutdown)(QIOChannel *ioc, |
| QIOChannelShutdown how, |
| Error **errp); |
| void (*io_set_cork)(QIOChannel *ioc, |
| bool enabled); |
| void (*io_set_delay)(QIOChannel *ioc, |
| bool enabled); |
| off_t (*io_seek)(QIOChannel *ioc, |
| off_t offset, |
| int whence, |
| Error **errp); |
| void (*io_set_aio_fd_handler)(QIOChannel *ioc, |
| AioContext *read_ctx, |
| IOHandler *io_read, |
| AioContext *write_ctx, |
| IOHandler *io_write, |
| void *opaque); |
| int (*io_flush)(QIOChannel *ioc, |
| Error **errp); |
| }; |
| |
| /* General I/O handling functions */ |
| |
| /** |
| * qio_channel_has_feature: |
| * @ioc: the channel object |
| * @feature: the feature to check support of |
| * |
| * Determine whether the channel implementation supports |
| * the optional feature named in @feature. |
| * |
| * Returns: true if supported, false otherwise. |
| */ |
| bool qio_channel_has_feature(QIOChannel *ioc, |
| QIOChannelFeature feature); |
| |
| /** |
| * qio_channel_set_feature: |
| * @ioc: the channel object |
| * @feature: the feature to set support for |
| * |
| * Add channel support for the feature named in @feature. |
| */ |
| void qio_channel_set_feature(QIOChannel *ioc, |
| QIOChannelFeature feature); |
| |
| /** |
| * qio_channel_set_name: |
| * @ioc: the channel object |
| * @name: the name of the channel |
| * |
| * Sets the name of the channel, which serves as an aid |
| * to debugging. The name is used when creating GSource |
| * watches for this channel. |
| */ |
| void qio_channel_set_name(QIOChannel *ioc, |
| const char *name); |
| |
| /** |
| * qio_channel_readv_full: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to read data into |
| * @niov: the length of the @iov array |
| * @fds: pointer to an array that will received file handles |
| * @nfds: pointer filled with number of elements in @fds on return |
| * @flags: read flags (QIO_CHANNEL_READ_FLAG_*) |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Read data from the IO channel, storing it in the |
| * memory regions referenced by @iov. Each element |
| * in the @iov will be fully populated with data |
| * before the next one is used. The @niov parameter |
| * specifies the total number of elements in @iov. |
| * |
| * It is not required for all @iov to be filled with |
| * data. If the channel is in blocking mode, at least |
| * one byte of data will be read, but no more is |
| * guaranteed. If the channel is non-blocking and no |
| * data is available, it will return QIO_CHANNEL_ERR_BLOCK |
| * |
| * If the channel has passed any file descriptors, |
| * the @fds array pointer will be allocated and |
| * the elements filled with the received file |
| * descriptors. The @nfds pointer will be updated |
| * to indicate the size of the @fds array that |
| * was allocated. It is the callers responsibility |
| * to call close() on each file descriptor and to |
| * call g_free() on the array pointer in @fds. |
| * |
| * It is an error to pass a non-NULL @fds parameter |
| * unless qio_channel_has_feature() returns a true |
| * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. |
| * |
| * Returns: the number of bytes read, or -1 on error, |
| * or QIO_CHANNEL_ERR_BLOCK if no data is available |
| * and the channel is non-blocking |
| */ |
| ssize_t qio_channel_readv_full(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| int **fds, |
| size_t *nfds, |
| int flags, |
| Error **errp); |
| |
| |
| /** |
| * qio_channel_writev_full: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to write data from |
| * @niov: the length of the @iov array |
| * @fds: an array of file handles to send |
| * @nfds: number of file handles in @fds |
| * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*) |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Write data to the IO channel, reading it from the |
| * memory regions referenced by @iov. Each element |
| * in the @iov will be fully sent, before the next |
| * one is used. The @niov parameter specifies the |
| * total number of elements in @iov. |
| * |
| * It is not required for all @iov data to be fully |
| * sent. If the channel is in blocking mode, at least |
| * one byte of data will be sent, but no more is |
| * guaranteed. If the channel is non-blocking and no |
| * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK |
| * |
| * If there are file descriptors to send, the @fds |
| * array should be non-NULL and provide the handles. |
| * All file descriptors will be sent if at least one |
| * byte of data was sent. |
| * |
| * It is an error to pass a non-NULL @fds parameter |
| * unless qio_channel_has_feature() returns a true |
| * value for the QIO_CHANNEL_FEATURE_FD_PASS constant. |
| * |
| * Returns: the number of bytes sent, or -1 on error, |
| * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent |
| * and the channel is non-blocking |
| */ |
| ssize_t qio_channel_writev_full(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| int *fds, |
| size_t nfds, |
| int flags, |
| Error **errp); |
| |
| /** |
| * qio_channel_readv_all_eof: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to read data into |
| * @niov: the length of the @iov array |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Read data from the IO channel, storing it in the |
| * memory regions referenced by @iov. Each element |
| * in the @iov will be fully populated with data |
| * before the next one is used. The @niov parameter |
| * specifies the total number of elements in @iov. |
| * |
| * The function will wait for all requested data |
| * to be read, yielding from the current coroutine |
| * if required. |
| * |
| * If end-of-file occurs before any data is read, |
| * no error is reported; otherwise, if it occurs |
| * before all requested data has been read, an error |
| * will be reported. |
| * |
| * Returns: 1 if all bytes were read, 0 if end-of-file |
| * occurs without data, or -1 on error |
| */ |
| int coroutine_mixed_fn qio_channel_readv_all_eof(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| Error **errp); |
| |
| /** |
| * qio_channel_readv_all: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to read data into |
| * @niov: the length of the @iov array |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Read data from the IO channel, storing it in the |
| * memory regions referenced by @iov. Each element |
| * in the @iov will be fully populated with data |
| * before the next one is used. The @niov parameter |
| * specifies the total number of elements in @iov. |
| * |
| * The function will wait for all requested data |
| * to be read, yielding from the current coroutine |
| * if required. |
| * |
| * If end-of-file occurs before all requested data |
| * has been read, an error will be reported. |
| * |
| * Returns: 0 if all bytes were read, or -1 on error |
| */ |
| int coroutine_mixed_fn qio_channel_readv_all(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| Error **errp); |
| |
| |
| /** |
| * qio_channel_writev_all: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to write data from |
| * @niov: the length of the @iov array |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Write data to the IO channel, reading it from the |
| * memory regions referenced by @iov. Each element |
| * in the @iov will be fully sent, before the next |
| * one is used. The @niov parameter specifies the |
| * total number of elements in @iov. |
| * |
| * The function will wait for all requested data |
| * to be written, yielding from the current coroutine |
| * if required. |
| * |
| * Returns: 0 if all bytes were written, or -1 on error |
| */ |
| int coroutine_mixed_fn qio_channel_writev_all(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| Error **errp); |
| |
| /** |
| * qio_channel_readv: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to read data into |
| * @niov: the length of the @iov array |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Behaves as qio_channel_readv_full() but does not support |
| * receiving of file handles. |
| */ |
| ssize_t qio_channel_readv(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| Error **errp); |
| |
| /** |
| * qio_channel_writev: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to write data from |
| * @niov: the length of the @iov array |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Behaves as qio_channel_writev_full() but does not support |
| * sending of file handles. |
| */ |
| ssize_t qio_channel_writev(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| Error **errp); |
| |
| /** |
| * qio_channel_read: |
| * @ioc: the channel object |
| * @buf: the memory region to read data into |
| * @buflen: the length of @buf |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Behaves as qio_channel_readv_full() but does not support |
| * receiving of file handles, and only supports reading into |
| * a single memory region. |
| */ |
| ssize_t qio_channel_read(QIOChannel *ioc, |
| char *buf, |
| size_t buflen, |
| Error **errp); |
| |
| /** |
| * qio_channel_write: |
| * @ioc: the channel object |
| * @buf: the memory regions to send data from |
| * @buflen: the length of @buf |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Behaves as qio_channel_writev_full() but does not support |
| * sending of file handles, and only supports writing from a |
| * single memory region. |
| */ |
| ssize_t qio_channel_write(QIOChannel *ioc, |
| const char *buf, |
| size_t buflen, |
| Error **errp); |
| |
| /** |
| * qio_channel_read_all_eof: |
| * @ioc: the channel object |
| * @buf: the memory region to read data into |
| * @buflen: the number of bytes to @buf |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Reads @buflen bytes into @buf, possibly blocking or (if the |
| * channel is non-blocking) yielding from the current coroutine |
| * multiple times until the entire content is read. If end-of-file |
| * occurs immediately it is not an error, but if it occurs after |
| * data has been read it will return an error rather than a |
| * short-read. Otherwise behaves as qio_channel_read(). |
| * |
| * Returns: 1 if all bytes were read, 0 if end-of-file occurs |
| * without data, or -1 on error |
| */ |
| int coroutine_mixed_fn qio_channel_read_all_eof(QIOChannel *ioc, |
| char *buf, |
| size_t buflen, |
| Error **errp); |
| |
| /** |
| * qio_channel_read_all: |
| * @ioc: the channel object |
| * @buf: the memory region to read data into |
| * @buflen: the number of bytes to @buf |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Reads @buflen bytes into @buf, possibly blocking or (if the |
| * channel is non-blocking) yielding from the current coroutine |
| * multiple times until the entire content is read. If end-of-file |
| * occurs it will return an error rather than a short-read. Otherwise |
| * behaves as qio_channel_read(). |
| * |
| * Returns: 0 if all bytes were read, or -1 on error |
| */ |
| int coroutine_mixed_fn qio_channel_read_all(QIOChannel *ioc, |
| char *buf, |
| size_t buflen, |
| Error **errp); |
| |
| /** |
| * qio_channel_write_all: |
| * @ioc: the channel object |
| * @buf: the memory region to write data into |
| * @buflen: the number of bytes to @buf |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Writes @buflen bytes from @buf, possibly blocking or (if the |
| * channel is non-blocking) yielding from the current coroutine |
| * multiple times until the entire content is written. Otherwise |
| * behaves as qio_channel_write(). |
| * |
| * Returns: 0 if all bytes were written, or -1 on error |
| */ |
| int coroutine_mixed_fn qio_channel_write_all(QIOChannel *ioc, |
| const char *buf, |
| size_t buflen, |
| Error **errp); |
| |
| /** |
| * qio_channel_set_blocking: |
| * @ioc: the channel object |
| * @enabled: the blocking flag state |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * If @enabled is true, then the channel is put into |
| * blocking mode, otherwise it will be non-blocking. |
| * |
| * In non-blocking mode, read/write operations may |
| * return QIO_CHANNEL_ERR_BLOCK if they would otherwise |
| * block on I/O |
| */ |
| int qio_channel_set_blocking(QIOChannel *ioc, |
| bool enabled, |
| Error **errp); |
| |
| /** |
| * qio_channel_set_follow_coroutine_ctx: |
| * @ioc: the channel object |
| * @enabled: whether or not to follow the coroutine's AioContext |
| * |
| * If @enabled is true, calls to qio_channel_yield() use the current |
| * coroutine's AioContext. Usually this is desirable. |
| * |
| * If @enabled is false, calls to qio_channel_yield() use the global iohandler |
| * AioContext. This is may be used by coroutines that run in the main loop and |
| * do not wish to respond to I/O during nested event loops. This is the |
| * default for compatibility with code that is not aware of AioContexts. |
| */ |
| void qio_channel_set_follow_coroutine_ctx(QIOChannel *ioc, bool enabled); |
| |
| /** |
| * qio_channel_close: |
| * @ioc: the channel object |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Close the channel, flushing any pending I/O |
| * |
| * Returns: 0 on success, -1 on error |
| */ |
| int qio_channel_close(QIOChannel *ioc, |
| Error **errp); |
| |
| /** |
| * qio_channel_pwritev |
| * @ioc: the channel object |
| * @iov: the array of memory regions to write data from |
| * @niov: the length of the @iov array |
| * @offset: offset in the channel where writes should begin |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Not all implementations will support this facility, so may report |
| * an error. To avoid errors, the caller may check for the feature |
| * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. |
| * |
| * Behaves as qio_channel_writev_full, apart from not supporting |
| * sending of file handles as well as beginning the write at the |
| * passed @offset |
| * |
| */ |
| ssize_t qio_channel_pwritev(QIOChannel *ioc, const struct iovec *iov, |
| size_t niov, off_t offset, Error **errp); |
| |
| /** |
| * qio_channel_pwrite |
| * @ioc: the channel object |
| * @buf: the memory region to write data into |
| * @buflen: the number of bytes to @buf |
| * @offset: offset in the channel where writes should begin |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Not all implementations will support this facility, so may report |
| * an error. To avoid errors, the caller may check for the feature |
| * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. |
| * |
| */ |
| ssize_t qio_channel_pwrite(QIOChannel *ioc, char *buf, size_t buflen, |
| off_t offset, Error **errp); |
| |
| /** |
| * qio_channel_preadv |
| * @ioc: the channel object |
| * @iov: the array of memory regions to read data into |
| * @niov: the length of the @iov array |
| * @offset: offset in the channel where writes should begin |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Not all implementations will support this facility, so may report |
| * an error. To avoid errors, the caller may check for the feature |
| * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. |
| * |
| * Behaves as qio_channel_readv_full, apart from not supporting |
| * receiving of file handles as well as beginning the read at the |
| * passed @offset |
| * |
| */ |
| ssize_t qio_channel_preadv(QIOChannel *ioc, const struct iovec *iov, |
| size_t niov, off_t offset, Error **errp); |
| |
| /** |
| * qio_channel_pread |
| * @ioc: the channel object |
| * @buf: the memory region to write data into |
| * @buflen: the number of bytes to @buf |
| * @offset: offset in the channel where writes should begin |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Not all implementations will support this facility, so may report |
| * an error. To avoid errors, the caller may check for the feature |
| * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method. |
| * |
| */ |
| ssize_t qio_channel_pread(QIOChannel *ioc, char *buf, size_t buflen, |
| off_t offset, Error **errp); |
| |
| /** |
| * qio_channel_shutdown: |
| * @ioc: the channel object |
| * @how: the direction to shutdown |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Shutdowns transmission and/or receiving of data |
| * without closing the underlying transport. |
| * |
| * Not all implementations will support this facility, |
| * so may report an error. To avoid errors, the |
| * caller may check for the feature flag |
| * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling |
| * this method. |
| * |
| * This function is thread-safe, terminates quickly and does not block. |
| * |
| * Returns: 0 on success, -1 on error |
| */ |
| int qio_channel_shutdown(QIOChannel *ioc, |
| QIOChannelShutdown how, |
| Error **errp); |
| |
| /** |
| * qio_channel_set_delay: |
| * @ioc: the channel object |
| * @enabled: the new flag state |
| * |
| * Controls whether the underlying transport is |
| * permitted to delay writes in order to merge |
| * small packets. If @enabled is true, then the |
| * writes may be delayed in order to opportunistically |
| * merge small packets into larger ones. If @enabled |
| * is false, writes are dispatched immediately with |
| * no delay. |
| * |
| * When @enabled is false, applications may wish to |
| * use the qio_channel_set_cork() method to explicitly |
| * control write merging. |
| * |
| * On channels which are backed by a socket, this |
| * API corresponds to the inverse of TCP_NODELAY flag, |
| * controlling whether the Nagle algorithm is active. |
| * |
| * This setting is merely a hint, so implementations are |
| * free to ignore this without it being considered an |
| * error. |
| */ |
| void qio_channel_set_delay(QIOChannel *ioc, |
| bool enabled); |
| |
| /** |
| * qio_channel_set_cork: |
| * @ioc: the channel object |
| * @enabled: the new flag state |
| * |
| * Controls whether the underlying transport is |
| * permitted to dispatch data that is written. |
| * If @enabled is true, then any data written will |
| * be queued in local buffers until @enabled is |
| * set to false once again. |
| * |
| * This feature is typically used when the automatic |
| * write coalescing facility is disabled via the |
| * qio_channel_set_delay() method. |
| * |
| * On channels which are backed by a socket, this |
| * API corresponds to the TCP_CORK flag. |
| * |
| * This setting is merely a hint, so implementations are |
| * free to ignore this without it being considered an |
| * error. |
| */ |
| void qio_channel_set_cork(QIOChannel *ioc, |
| bool enabled); |
| |
| |
| /** |
| * qio_channel_seek: |
| * @ioc: the channel object |
| * @offset: the position to seek to, relative to @whence |
| * @whence: one of the (POSIX) SEEK_* constants listed below |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Moves the current I/O position within the channel |
| * @ioc, to be @offset. The value of @offset is |
| * interpreted relative to @whence: |
| * |
| * SEEK_SET - the position is set to @offset bytes |
| * SEEK_CUR - the position is moved by @offset bytes |
| * SEEK_END - the position is set to end of the file plus @offset bytes |
| * |
| * Not all implementations will support this facility, |
| * so may report an error. |
| * |
| * Returns: the new position on success, (off_t)-1 on failure |
| */ |
| off_t qio_channel_io_seek(QIOChannel *ioc, |
| off_t offset, |
| int whence, |
| Error **errp); |
| |
| |
| /** |
| * qio_channel_create_watch: |
| * @ioc: the channel object |
| * @condition: the I/O condition to monitor |
| * |
| * Create a new main loop source that is used to watch |
| * for the I/O condition @condition. Typically the |
| * qio_channel_add_watch() method would be used instead |
| * of this, since it directly attaches a callback to |
| * the source |
| * |
| * Returns: the new main loop source. |
| */ |
| GSource *qio_channel_create_watch(QIOChannel *ioc, |
| GIOCondition condition); |
| |
| /** |
| * qio_channel_add_watch: |
| * @ioc: the channel object |
| * @condition: the I/O condition to monitor |
| * @func: callback to invoke when the source becomes ready |
| * @user_data: opaque data to pass to @func |
| * @notify: callback to free @user_data |
| * |
| * Create a new main loop source that is used to watch |
| * for the I/O condition @condition. The callback @func |
| * will be registered against the source, to be invoked |
| * when the source becomes ready. The optional @user_data |
| * will be passed to @func when it is invoked. The @notify |
| * callback will be used to free @user_data when the |
| * watch is deleted |
| * |
| * The returned source ID can be used with g_source_remove() |
| * to remove and free the source when no longer required. |
| * Alternatively the @func callback can return a FALSE |
| * value. |
| * |
| * Returns: the source ID |
| */ |
| guint qio_channel_add_watch(QIOChannel *ioc, |
| GIOCondition condition, |
| QIOChannelFunc func, |
| gpointer user_data, |
| GDestroyNotify notify); |
| |
| /** |
| * qio_channel_add_watch_full: |
| * @ioc: the channel object |
| * @condition: the I/O condition to monitor |
| * @func: callback to invoke when the source becomes ready |
| * @user_data: opaque data to pass to @func |
| * @notify: callback to free @user_data |
| * @context: the context to run the watch source |
| * |
| * Similar as qio_channel_add_watch(), but allows to specify context |
| * to run the watch source. |
| * |
| * Returns: the source ID |
| */ |
| guint qio_channel_add_watch_full(QIOChannel *ioc, |
| GIOCondition condition, |
| QIOChannelFunc func, |
| gpointer user_data, |
| GDestroyNotify notify, |
| GMainContext *context); |
| |
| /** |
| * qio_channel_add_watch_source: |
| * @ioc: the channel object |
| * @condition: the I/O condition to monitor |
| * @func: callback to invoke when the source becomes ready |
| * @user_data: opaque data to pass to @func |
| * @notify: callback to free @user_data |
| * @context: gcontext to bind the source to |
| * |
| * Similar as qio_channel_add_watch(), but allows to specify context |
| * to run the watch source, meanwhile return the GSource object |
| * instead of tag ID, with the GSource referenced already. |
| * |
| * Note: callers is responsible to unref the source when not needed. |
| * |
| * Returns: the source pointer |
| */ |
| GSource *qio_channel_add_watch_source(QIOChannel *ioc, |
| GIOCondition condition, |
| QIOChannelFunc func, |
| gpointer user_data, |
| GDestroyNotify notify, |
| GMainContext *context); |
| |
| /** |
| * qio_channel_yield: |
| * @ioc: the channel object |
| * @condition: the I/O condition to wait for |
| * |
| * Yields execution from the current coroutine until the condition |
| * indicated by @condition becomes available. @condition must |
| * be either %G_IO_IN or %G_IO_OUT; it cannot contain both. In |
| * addition, no two coroutine can be waiting on the same condition |
| * and channel at the same time. |
| * |
| * This must only be called from coroutine context. It is safe to |
| * reenter the coroutine externally while it is waiting; in this |
| * case the function will return even if @condition is not yet |
| * available. |
| */ |
| void coroutine_fn qio_channel_yield(QIOChannel *ioc, |
| GIOCondition condition); |
| |
| /** |
| * qio_channel_wake_read: |
| * @ioc: the channel object |
| * |
| * If qio_channel_yield() is currently waiting for the channel to become |
| * readable, interrupt it and reenter immediately. This function is safe to call |
| * from any thread. |
| */ |
| void qio_channel_wake_read(QIOChannel *ioc); |
| |
| /** |
| * qio_channel_wait: |
| * @ioc: the channel object |
| * @condition: the I/O condition to wait for |
| * |
| * Block execution from the current thread until |
| * the condition indicated by @condition becomes |
| * available. |
| * |
| * This will enter a nested event loop to perform |
| * the wait. |
| */ |
| void qio_channel_wait(QIOChannel *ioc, |
| GIOCondition condition); |
| |
| /** |
| * qio_channel_set_aio_fd_handler: |
| * @ioc: the channel object |
| * @read_ctx: the AioContext to set the read handler on or NULL |
| * @io_read: the read handler |
| * @write_ctx: the AioContext to set the write handler on or NULL |
| * @io_write: the write handler |
| * @opaque: the opaque value passed to the handler |
| * |
| * This is used internally by qio_channel_yield(). It can |
| * be used by channel implementations to forward the handlers |
| * to another channel (e.g. from #QIOChannelTLS to the |
| * underlying socket). |
| * |
| * When @read_ctx is NULL, don't touch the read handler. When @write_ctx is |
| * NULL, don't touch the write handler. Note that setting the read handler |
| * clears the write handler, and vice versa, if they share the same AioContext. |
| * Therefore the caller must pass both handlers together when sharing the same |
| * AioContext. |
| */ |
| void qio_channel_set_aio_fd_handler(QIOChannel *ioc, |
| AioContext *read_ctx, |
| IOHandler *io_read, |
| AioContext *write_ctx, |
| IOHandler *io_write, |
| void *opaque); |
| |
| /** |
| * qio_channel_readv_full_all_eof: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to read data to |
| * @niov: the length of the @iov array |
| * @fds: an array of file handles to read |
| * @nfds: number of file handles in @fds |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * |
| * Performs same function as qio_channel_readv_all_eof. |
| * Additionally, attempts to read file descriptors shared |
| * over the channel. The function will wait for all |
| * requested data to be read, yielding from the current |
| * coroutine if required. data refers to both file |
| * descriptors and the iovs. |
| * |
| * Returns: 1 if all bytes were read, 0 if end-of-file |
| * occurs without data, or -1 on error |
| */ |
| |
| int coroutine_mixed_fn qio_channel_readv_full_all_eof(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| int **fds, size_t *nfds, |
| Error **errp); |
| |
| /** |
| * qio_channel_readv_full_all: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to read data to |
| * @niov: the length of the @iov array |
| * @fds: an array of file handles to read |
| * @nfds: number of file handles in @fds |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * |
| * Performs same function as qio_channel_readv_all_eof. |
| * Additionally, attempts to read file descriptors shared |
| * over the channel. The function will wait for all |
| * requested data to be read, yielding from the current |
| * coroutine if required. data refers to both file |
| * descriptors and the iovs. |
| * |
| * Returns: 0 if all bytes were read, or -1 on error |
| */ |
| |
| int coroutine_mixed_fn qio_channel_readv_full_all(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| int **fds, size_t *nfds, |
| Error **errp); |
| |
| /** |
| * qio_channel_writev_full_all: |
| * @ioc: the channel object |
| * @iov: the array of memory regions to write data from |
| * @niov: the length of the @iov array |
| * @fds: an array of file handles to send |
| * @nfds: number of file handles in @fds |
| * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*) |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * |
| * Behaves like qio_channel_writev_full but will attempt |
| * to send all data passed (file handles and memory regions). |
| * The function will wait for all requested data |
| * to be written, yielding from the current coroutine |
| * if required. |
| * |
| * If QIO_CHANNEL_WRITE_FLAG_ZERO_COPY is passed in flags, |
| * instead of waiting for all requested data to be written, |
| * this function will wait until it's all queued for writing. |
| * In this case, if the buffer gets changed between queueing and |
| * sending, the updated buffer will be sent. If this is not a |
| * desired behavior, it's suggested to call qio_channel_flush() |
| * before reusing the buffer. |
| * |
| * Returns: 0 if all bytes were written, or -1 on error |
| */ |
| |
| int coroutine_mixed_fn qio_channel_writev_full_all(QIOChannel *ioc, |
| const struct iovec *iov, |
| size_t niov, |
| int *fds, size_t nfds, |
| int flags, Error **errp); |
| |
| /** |
| * qio_channel_flush: |
| * @ioc: the channel object |
| * @errp: pointer to a NULL-initialized error object |
| * |
| * Will block until every packet queued with |
| * qio_channel_writev_full() + QIO_CHANNEL_WRITE_FLAG_ZERO_COPY |
| * is sent, or return in case of any error. |
| * |
| * If not implemented, acts as a no-op, and returns 0. |
| * |
| * Returns -1 if any error is found, |
| * 1 if every send failed to use zero copy. |
| * 0 otherwise. |
| */ |
| |
| int qio_channel_flush(QIOChannel *ioc, |
| Error **errp); |
| |
| #endif /* QIO_CHANNEL_H */ |
