| /* | |
| * 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 "qemu/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 | |
| #define QIO_CHANNEL_READ_FLAG_RELAXED_EOF 0x2 | |
| #define QIO_CHANNEL_READ_FLAG_FD_PRESERVE_BLOCKING 0x4 | |
| 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); | |
| /* | |
| * The io_readv handler must guarantee that all | |
| * incoming fds are set BLOCKING (unless | |
| * QIO_CHANNEL_READ_FLAG_FD_PRESERVE_BLOCKING flag is set) and | |
| * CLOEXEC (if available). | |
| * @fds and @nfds are set only on success path. Still, setting | |
| * @fds and @nfds to zero is acceptable on failure path. | |
| */ | |
| 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); | |
| int (*io_peerpid)(QIOChannel *ioc, | |
| unsigned int *pid, | |
| 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. | |
| * @fds allocated and set (and @nfds is set too) | |
| * _only_ on success path. Still, @fds and @nfds | |
| * may be set to zero on failure path. | |
| * qio_channel_readv_full() guarantees that all | |
| * incoming fds are set BLOCKING (unless | |
| * QIO_CHANNEL_READ_FLAG_FD_PRESERVE_BLOCKING flag | |
| * is set) and CLOEXEC (if available). | |
| * | |
| * 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, | |
| void *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 void *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, | |
| void *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, | |
| void *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 void *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 | |
| */ | |
| bool 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, void *buf, size_t buflen, | |
| off_t offset, Error **errp); | |
| /** | |
| * qio_channel_pwritev_all: | |
| * @ioc: the channel object | |
| * @iov: the array of memory regions to write data from | |
| * @niov: the length of the @iov array | |
| * @offset: the starting offset in the channel to write to | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Writes @iov, 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_pwritev(). | |
| * | |
| * Returns: 0 if all bytes were written, or -1 on error | |
| */ | |
| int coroutine_mixed_fn qio_channel_pwritev_all(QIOChannel *ioc, | |
| const struct iovec *iov, | |
| size_t niov, | |
| off_t offset, | |
| Error **errp); | |
| /** | |
| * qio_channel_pwrite_all: | |
| * @ioc: the channel object | |
| * @buf: the memory region to write data from | |
| * @buflen: the number of bytes to write from @buf | |
| * @offset: the starting offset in the channel to write to | |
| * @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_pwrite(). | |
| * | |
| * Returns: 0 if all bytes were written, or -1 on error | |
| */ | |
| int coroutine_mixed_fn qio_channel_pwrite_all(QIOChannel *ioc, | |
| const void *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, void *buf, size_t buflen, | |
| off_t offset, Error **errp); | |
| /** | |
| * qio_channel_preadv_all_eof: | |
| * @ioc: the channel object | |
| * @iov: the array of memory regions to read data into | |
| * @niov: the length of the @iov array | |
| * @offset: the starting offset in the channel to read from | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Reads @iov, 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_preadv(). | |
| * | |
| * 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_preadv_all_eof(QIOChannel *ioc, | |
| const struct iovec *iov, | |
| size_t niov, | |
| off_t offset, | |
| Error **errp); | |
| /** | |
| * qio_channel_preadv_all: | |
| * @ioc: the channel object | |
| * @iov: the array of memory regions to read data into | |
| * @niov: the length of the @iov array | |
| * @offset: the starting offset in the channel to read from | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Reads @iov, 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 before all requested data | |
| * has been read, an error will be reported. Otherwise behaves as | |
| * qio_channel_preadv(). | |
| * | |
| * Returns: 0 if all bytes were read, or -1 on error | |
| */ | |
| int coroutine_mixed_fn qio_channel_preadv_all(QIOChannel *ioc, | |
| const struct iovec *iov, | |
| size_t niov, | |
| off_t offset, | |
| Error **errp); | |
| /** | |
| * qio_channel_pread_all_eof: | |
| * @ioc: the channel object | |
| * @buf: the memory region to read data into | |
| * @buflen: the number of bytes to read into @buf | |
| * @offset: the starting offset in the channel to read from | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Reads @buflen bytes, 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_pread(). | |
| * | |
| * 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_pread_all_eof(QIOChannel *ioc, | |
| void *buf, | |
| size_t buflen, | |
| off_t offset, | |
| Error **errp); | |
| /** | |
| * qio_channel_pread_all: | |
| * @ioc: the channel object | |
| * @buf: the memory region to read data into | |
| * @buflen: the number of bytes to read into @buf | |
| * @offset: the starting offset in the channel to read from | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Reads @buflen bytes, 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 before | |
| * all requested data has been read, an error will be reported. | |
| * Otherwise behaves as qio_channel_pread(). | |
| * | |
| * Returns: 0 if all bytes were read, or -1 on error | |
| */ | |
| int coroutine_mixed_fn qio_channel_pread_all(QIOChannel *ioc, | |
| void *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_wait_cond: | |
| * @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 work with/without a coroutine context, by automatically select | |
| * the proper API to wait. | |
| */ | |
| void coroutine_mixed_fn qio_channel_wait_cond(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 | |
| * @flags: read flags (QIO_CHANNEL_READ_FLAG_*) | |
| * @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, | |
| int flags, | |
| 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 at least one send failed to use zero copy. | |
| * 0 if every send successfully used zero copy. | |
| */ | |
| int qio_channel_flush(QIOChannel *ioc, | |
| Error **errp); | |
| /** | |
| * qio_channel_get_peercred: | |
| * @ioc: the channel object | |
| * @pid: pointer to pid | |
| * @errp: pointer to a NULL-initialized error object | |
| * | |
| * Returns the pid of the peer process connected to this socket. | |
| * | |
| * The use of this function is possible only for connected | |
| * AF_UNIX stream sockets and for AF_UNIX stream and datagram | |
| * socket pairs on Linux. | |
| * Return -1 on error with pid -1 for the non-Linux OS. | |
| * | |
| */ | |
| int qio_channel_get_peerpid(QIOChannel *ioc, | |
| unsigned int *pid, | |
| Error **errp); | |
| #endif /* QIO_CHANNEL_H */ |