4 * Copyright (c) 2015 Red Hat, Inc.
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.1 of the License, or (at your option) any later version.
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.
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/>.
24 #include "qom/object.h"
25 #include "qemu/coroutine-core.h"
26 #include "block/aio.h"
28 #define TYPE_QIO_CHANNEL "qio-channel"
29 OBJECT_DECLARE_TYPE(QIOChannel
, QIOChannelClass
,
33 #define QIO_CHANNEL_ERR_BLOCK -2
35 #define QIO_CHANNEL_WRITE_FLAG_ZERO_COPY 0x1
37 #define QIO_CHANNEL_READ_FLAG_MSG_PEEK 0x1
39 typedef enum QIOChannelFeature QIOChannelFeature
;
41 enum QIOChannelFeature
{
42 QIO_CHANNEL_FEATURE_FD_PASS
,
43 QIO_CHANNEL_FEATURE_SHUTDOWN
,
44 QIO_CHANNEL_FEATURE_LISTEN
,
45 QIO_CHANNEL_FEATURE_WRITE_ZERO_COPY
,
46 QIO_CHANNEL_FEATURE_READ_MSG_PEEK
,
47 QIO_CHANNEL_FEATURE_SEEKABLE
,
51 typedef enum QIOChannelShutdown QIOChannelShutdown
;
53 enum QIOChannelShutdown
{
54 QIO_CHANNEL_SHUTDOWN_READ
= 1,
55 QIO_CHANNEL_SHUTDOWN_WRITE
= 2,
56 QIO_CHANNEL_SHUTDOWN_BOTH
= 3,
59 typedef gboolean (*QIOChannelFunc
)(QIOChannel
*ioc
,
60 GIOCondition condition
,
66 * The QIOChannel defines the core API for a generic I/O channel
67 * class hierarchy. It is inspired by GIOChannel, but has the
68 * following differences
70 * - Use QOM to properly support arbitrary subclassing
71 * - Support use of iovecs for efficient I/O with multiple blocks
72 * - None of the character set translation, binary data exclusively
73 * - Direct support for QEMU Error object reporting
74 * - File descriptor passing
76 * This base class is abstract so cannot be instantiated. There
77 * will be subclasses for dealing with sockets, files, and higher
78 * level protocols such as TLS, WebSocket, etc.
83 unsigned int features
; /* bitmask of QIOChannelFeatures */
86 Coroutine
*read_coroutine
;
87 AioContext
*write_ctx
;
88 Coroutine
*write_coroutine
;
89 bool follow_coroutine_ctx
;
91 HANDLE event
; /* For use with GSource on Win32 */
98 * This class defines the contract that all subclasses
99 * must follow to provide specific channel implementations.
100 * The first five callbacks are mandatory to support, others
101 * provide additional optional features.
103 * Consult the corresponding public API docs for a description
104 * of the semantics of each callback. io_shutdown in particular
105 * must be thread-safe, terminate quickly and must not block.
107 struct QIOChannelClass
{
110 /* Mandatory callbacks */
111 ssize_t (*io_writev
)(QIOChannel
*ioc
,
112 const struct iovec
*iov
,
118 ssize_t (*io_readv
)(QIOChannel
*ioc
,
119 const struct iovec
*iov
,
125 int (*io_close
)(QIOChannel
*ioc
,
127 GSource
* (*io_create_watch
)(QIOChannel
*ioc
,
128 GIOCondition condition
);
129 int (*io_set_blocking
)(QIOChannel
*ioc
,
133 /* Optional callbacks */
134 ssize_t (*io_pwritev
)(QIOChannel
*ioc
,
135 const struct iovec
*iov
,
139 ssize_t (*io_preadv
)(QIOChannel
*ioc
,
140 const struct iovec
*iov
,
144 int (*io_shutdown
)(QIOChannel
*ioc
,
145 QIOChannelShutdown how
,
147 void (*io_set_cork
)(QIOChannel
*ioc
,
149 void (*io_set_delay
)(QIOChannel
*ioc
,
151 off_t (*io_seek
)(QIOChannel
*ioc
,
155 void (*io_set_aio_fd_handler
)(QIOChannel
*ioc
,
156 AioContext
*read_ctx
,
158 AioContext
*write_ctx
,
161 int (*io_flush
)(QIOChannel
*ioc
,
165 /* General I/O handling functions */
168 * qio_channel_has_feature:
169 * @ioc: the channel object
170 * @feature: the feature to check support of
172 * Determine whether the channel implementation supports
173 * the optional feature named in @feature.
175 * Returns: true if supported, false otherwise.
177 bool qio_channel_has_feature(QIOChannel
*ioc
,
178 QIOChannelFeature feature
);
181 * qio_channel_set_feature:
182 * @ioc: the channel object
183 * @feature: the feature to set support for
185 * Add channel support for the feature named in @feature.
187 void qio_channel_set_feature(QIOChannel
*ioc
,
188 QIOChannelFeature feature
);
191 * qio_channel_set_name:
192 * @ioc: the channel object
193 * @name: the name of the channel
195 * Sets the name of the channel, which serves as an aid
196 * to debugging. The name is used when creating GSource
197 * watches for this channel.
199 void qio_channel_set_name(QIOChannel
*ioc
,
203 * qio_channel_readv_full:
204 * @ioc: the channel object
205 * @iov: the array of memory regions to read data into
206 * @niov: the length of the @iov array
207 * @fds: pointer to an array that will received file handles
208 * @nfds: pointer filled with number of elements in @fds on return
209 * @flags: read flags (QIO_CHANNEL_READ_FLAG_*)
210 * @errp: pointer to a NULL-initialized error object
212 * Read data from the IO channel, storing it in the
213 * memory regions referenced by @iov. Each element
214 * in the @iov will be fully populated with data
215 * before the next one is used. The @niov parameter
216 * specifies the total number of elements in @iov.
218 * It is not required for all @iov to be filled with
219 * data. If the channel is in blocking mode, at least
220 * one byte of data will be read, but no more is
221 * guaranteed. If the channel is non-blocking and no
222 * data is available, it will return QIO_CHANNEL_ERR_BLOCK
224 * If the channel has passed any file descriptors,
225 * the @fds array pointer will be allocated and
226 * the elements filled with the received file
227 * descriptors. The @nfds pointer will be updated
228 * to indicate the size of the @fds array that
229 * was allocated. It is the callers responsibility
230 * to call close() on each file descriptor and to
231 * call g_free() on the array pointer in @fds.
233 * It is an error to pass a non-NULL @fds parameter
234 * unless qio_channel_has_feature() returns a true
235 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
237 * Returns: the number of bytes read, or -1 on error,
238 * or QIO_CHANNEL_ERR_BLOCK if no data is available
239 * and the channel is non-blocking
241 ssize_t
qio_channel_readv_full(QIOChannel
*ioc
,
242 const struct iovec
*iov
,
251 * qio_channel_writev_full:
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 * @fds: an array of file handles to send
256 * @nfds: number of file handles in @fds
257 * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*)
258 * @errp: pointer to a NULL-initialized error object
260 * Write data to the IO channel, reading it from the
261 * memory regions referenced by @iov. Each element
262 * in the @iov will be fully sent, before the next
263 * one is used. The @niov parameter specifies the
264 * total number of elements in @iov.
266 * It is not required for all @iov data to be fully
267 * sent. If the channel is in blocking mode, at least
268 * one byte of data will be sent, but no more is
269 * guaranteed. If the channel is non-blocking and no
270 * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK
272 * If there are file descriptors to send, the @fds
273 * array should be non-NULL and provide the handles.
274 * All file descriptors will be sent if at least one
275 * byte of data was sent.
277 * It is an error to pass a non-NULL @fds parameter
278 * unless qio_channel_has_feature() returns a true
279 * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
281 * Returns: the number of bytes sent, or -1 on error,
282 * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent
283 * and the channel is non-blocking
285 ssize_t
qio_channel_writev_full(QIOChannel
*ioc
,
286 const struct iovec
*iov
,
294 * qio_channel_readv_all_eof:
295 * @ioc: the channel object
296 * @iov: the array of memory regions to read data into
297 * @niov: the length of the @iov array
298 * @errp: pointer to a NULL-initialized error object
300 * Read data from the IO channel, storing it in the
301 * memory regions referenced by @iov. Each element
302 * in the @iov will be fully populated with data
303 * before the next one is used. The @niov parameter
304 * specifies the total number of elements in @iov.
306 * The function will wait for all requested data
307 * to be read, yielding from the current coroutine
310 * If end-of-file occurs before any data is read,
311 * no error is reported; otherwise, if it occurs
312 * before all requested data has been read, an error
315 * Returns: 1 if all bytes were read, 0 if end-of-file
316 * occurs without data, or -1 on error
318 int coroutine_mixed_fn
qio_channel_readv_all_eof(QIOChannel
*ioc
,
319 const struct iovec
*iov
,
324 * qio_channel_readv_all:
325 * @ioc: the channel object
326 * @iov: the array of memory regions to read data into
327 * @niov: the length of the @iov array
328 * @errp: pointer to a NULL-initialized error object
330 * Read data from the IO channel, storing it in the
331 * memory regions referenced by @iov. Each element
332 * in the @iov will be fully populated with data
333 * before the next one is used. The @niov parameter
334 * specifies the total number of elements in @iov.
336 * The function will wait for all requested data
337 * to be read, yielding from the current coroutine
340 * If end-of-file occurs before all requested data
341 * has been read, an error will be reported.
343 * Returns: 0 if all bytes were read, or -1 on error
345 int coroutine_mixed_fn
qio_channel_readv_all(QIOChannel
*ioc
,
346 const struct iovec
*iov
,
352 * qio_channel_writev_all:
353 * @ioc: the channel object
354 * @iov: the array of memory regions to write data from
355 * @niov: the length of the @iov array
356 * @errp: pointer to a NULL-initialized error object
358 * Write data to the IO channel, reading it from the
359 * memory regions referenced by @iov. Each element
360 * in the @iov will be fully sent, before the next
361 * one is used. The @niov parameter specifies the
362 * total number of elements in @iov.
364 * The function will wait for all requested data
365 * to be written, yielding from the current coroutine
368 * Returns: 0 if all bytes were written, or -1 on error
370 int coroutine_mixed_fn
qio_channel_writev_all(QIOChannel
*ioc
,
371 const struct iovec
*iov
,
377 * @ioc: the channel object
378 * @iov: the array of memory regions to read data into
379 * @niov: the length of the @iov array
380 * @errp: pointer to a NULL-initialized error object
382 * Behaves as qio_channel_readv_full() but does not support
383 * receiving of file handles.
385 ssize_t
qio_channel_readv(QIOChannel
*ioc
,
386 const struct iovec
*iov
,
391 * qio_channel_writev:
392 * @ioc: the channel object
393 * @iov: the array of memory regions to write data from
394 * @niov: the length of the @iov array
395 * @errp: pointer to a NULL-initialized error object
397 * Behaves as qio_channel_writev_full() but does not support
398 * sending of file handles.
400 ssize_t
qio_channel_writev(QIOChannel
*ioc
,
401 const struct iovec
*iov
,
407 * @ioc: the channel object
408 * @buf: the memory region to read data into
409 * @buflen: the length of @buf
410 * @errp: pointer to a NULL-initialized error object
412 * Behaves as qio_channel_readv_full() but does not support
413 * receiving of file handles, and only supports reading into
414 * a single memory region.
416 ssize_t
qio_channel_read(QIOChannel
*ioc
,
423 * @ioc: the channel object
424 * @buf: the memory regions to send data from
425 * @buflen: the length of @buf
426 * @errp: pointer to a NULL-initialized error object
428 * Behaves as qio_channel_writev_full() but does not support
429 * sending of file handles, and only supports writing from a
430 * single memory region.
432 ssize_t
qio_channel_write(QIOChannel
*ioc
,
438 * qio_channel_read_all_eof:
439 * @ioc: the channel object
440 * @buf: the memory region to read data into
441 * @buflen: the number of bytes to @buf
442 * @errp: pointer to a NULL-initialized error object
444 * Reads @buflen bytes into @buf, possibly blocking or (if the
445 * channel is non-blocking) yielding from the current coroutine
446 * multiple times until the entire content is read. If end-of-file
447 * occurs immediately it is not an error, but if it occurs after
448 * data has been read it will return an error rather than a
449 * short-read. Otherwise behaves as qio_channel_read().
451 * Returns: 1 if all bytes were read, 0 if end-of-file occurs
452 * without data, or -1 on error
454 int coroutine_mixed_fn
qio_channel_read_all_eof(QIOChannel
*ioc
,
460 * qio_channel_read_all:
461 * @ioc: the channel object
462 * @buf: the memory region to read data into
463 * @buflen: the number of bytes to @buf
464 * @errp: pointer to a NULL-initialized error object
466 * Reads @buflen bytes into @buf, possibly blocking or (if the
467 * channel is non-blocking) yielding from the current coroutine
468 * multiple times until the entire content is read. If end-of-file
469 * occurs it will return an error rather than a short-read. Otherwise
470 * behaves as qio_channel_read().
472 * Returns: 0 if all bytes were read, or -1 on error
474 int coroutine_mixed_fn
qio_channel_read_all(QIOChannel
*ioc
,
480 * qio_channel_write_all:
481 * @ioc: the channel object
482 * @buf: the memory region to write data into
483 * @buflen: the number of bytes to @buf
484 * @errp: pointer to a NULL-initialized error object
486 * Writes @buflen bytes from @buf, possibly blocking or (if the
487 * channel is non-blocking) yielding from the current coroutine
488 * multiple times until the entire content is written. Otherwise
489 * behaves as qio_channel_write().
491 * Returns: 0 if all bytes were written, or -1 on error
493 int coroutine_mixed_fn
qio_channel_write_all(QIOChannel
*ioc
,
499 * qio_channel_set_blocking:
500 * @ioc: the channel object
501 * @enabled: the blocking flag state
502 * @errp: pointer to a NULL-initialized error object
504 * If @enabled is true, then the channel is put into
505 * blocking mode, otherwise it will be non-blocking.
507 * In non-blocking mode, read/write operations may
508 * return QIO_CHANNEL_ERR_BLOCK if they would otherwise
511 int qio_channel_set_blocking(QIOChannel
*ioc
,
516 * qio_channel_set_follow_coroutine_ctx:
517 * @ioc: the channel object
518 * @enabled: whether or not to follow the coroutine's AioContext
520 * If @enabled is true, calls to qio_channel_yield() use the current
521 * coroutine's AioContext. Usually this is desirable.
523 * If @enabled is false, calls to qio_channel_yield() use the global iohandler
524 * AioContext. This is may be used by coroutines that run in the main loop and
525 * do not wish to respond to I/O during nested event loops. This is the
526 * default for compatibility with code that is not aware of AioContexts.
528 void qio_channel_set_follow_coroutine_ctx(QIOChannel
*ioc
, bool enabled
);
532 * @ioc: the channel object
533 * @errp: pointer to a NULL-initialized error object
535 * Close the channel, flushing any pending I/O
537 * Returns: 0 on success, -1 on error
539 int qio_channel_close(QIOChannel
*ioc
,
543 * qio_channel_pwritev
544 * @ioc: the channel object
545 * @iov: the array of memory regions to write data from
546 * @niov: the length of the @iov array
547 * @offset: offset in the channel where writes should begin
548 * @errp: pointer to a NULL-initialized error object
550 * Not all implementations will support this facility, so may report
551 * an error. To avoid errors, the caller may check for the feature
552 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
554 * Behaves as qio_channel_writev_full, apart from not supporting
555 * sending of file handles as well as beginning the write at the
559 ssize_t
qio_channel_pwritev(QIOChannel
*ioc
, const struct iovec
*iov
,
560 size_t niov
, off_t offset
, Error
**errp
);
564 * @ioc: the channel object
565 * @buf: the memory region to write data into
566 * @buflen: the number of bytes to @buf
567 * @offset: offset in the channel where writes should begin
568 * @errp: pointer to a NULL-initialized error object
570 * Not all implementations will support this facility, so may report
571 * an error. To avoid errors, the caller may check for the feature
572 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
575 ssize_t
qio_channel_pwrite(QIOChannel
*ioc
, char *buf
, size_t buflen
,
576 off_t offset
, Error
**errp
);
580 * @ioc: the channel object
581 * @iov: the array of memory regions to read data into
582 * @niov: the length of the @iov array
583 * @offset: offset in the channel where writes should begin
584 * @errp: pointer to a NULL-initialized error object
586 * Not all implementations will support this facility, so may report
587 * an error. To avoid errors, the caller may check for the feature
588 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
590 * Behaves as qio_channel_readv_full, apart from not supporting
591 * receiving of file handles as well as beginning the read at the
595 ssize_t
qio_channel_preadv(QIOChannel
*ioc
, const struct iovec
*iov
,
596 size_t niov
, off_t offset
, Error
**errp
);
600 * @ioc: the channel object
601 * @buf: the memory region to write data into
602 * @buflen: the number of bytes to @buf
603 * @offset: offset in the channel where writes should begin
604 * @errp: pointer to a NULL-initialized error object
606 * Not all implementations will support this facility, so may report
607 * an error. To avoid errors, the caller may check for the feature
608 * flag QIO_CHANNEL_FEATURE_SEEKABLE prior to calling this method.
611 ssize_t
qio_channel_pread(QIOChannel
*ioc
, char *buf
, size_t buflen
,
612 off_t offset
, Error
**errp
);
615 * qio_channel_shutdown:
616 * @ioc: the channel object
617 * @how: the direction to shutdown
618 * @errp: pointer to a NULL-initialized error object
620 * Shutdowns transmission and/or receiving of data
621 * without closing the underlying transport.
623 * Not all implementations will support this facility,
624 * so may report an error. To avoid errors, the
625 * caller may check for the feature flag
626 * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling
629 * This function is thread-safe, terminates quickly and does not block.
631 * Returns: 0 on success, -1 on error
633 int qio_channel_shutdown(QIOChannel
*ioc
,
634 QIOChannelShutdown how
,
638 * qio_channel_set_delay:
639 * @ioc: the channel object
640 * @enabled: the new flag state
642 * Controls whether the underlying transport is
643 * permitted to delay writes in order to merge
644 * small packets. If @enabled is true, then the
645 * writes may be delayed in order to opportunistically
646 * merge small packets into larger ones. If @enabled
647 * is false, writes are dispatched immediately with
650 * When @enabled is false, applications may wish to
651 * use the qio_channel_set_cork() method to explicitly
652 * control write merging.
654 * On channels which are backed by a socket, this
655 * API corresponds to the inverse of TCP_NODELAY flag,
656 * controlling whether the Nagle algorithm is active.
658 * This setting is merely a hint, so implementations are
659 * free to ignore this without it being considered an
662 void qio_channel_set_delay(QIOChannel
*ioc
,
666 * qio_channel_set_cork:
667 * @ioc: the channel object
668 * @enabled: the new flag state
670 * Controls whether the underlying transport is
671 * permitted to dispatch data that is written.
672 * If @enabled is true, then any data written will
673 * be queued in local buffers until @enabled is
674 * set to false once again.
676 * This feature is typically used when the automatic
677 * write coalescing facility is disabled via the
678 * qio_channel_set_delay() method.
680 * On channels which are backed by a socket, this
681 * API corresponds to the TCP_CORK flag.
683 * This setting is merely a hint, so implementations are
684 * free to ignore this without it being considered an
687 void qio_channel_set_cork(QIOChannel
*ioc
,
693 * @ioc: the channel object
694 * @offset: the position to seek to, relative to @whence
695 * @whence: one of the (POSIX) SEEK_* constants listed below
696 * @errp: pointer to a NULL-initialized error object
698 * Moves the current I/O position within the channel
699 * @ioc, to be @offset. The value of @offset is
700 * interpreted relative to @whence:
702 * SEEK_SET - the position is set to @offset bytes
703 * SEEK_CUR - the position is moved by @offset bytes
704 * SEEK_END - the position is set to end of the file plus @offset bytes
706 * Not all implementations will support this facility,
707 * so may report an error.
709 * Returns: the new position on success, (off_t)-1 on failure
711 off_t
qio_channel_io_seek(QIOChannel
*ioc
,
718 * qio_channel_create_watch:
719 * @ioc: the channel object
720 * @condition: the I/O condition to monitor
722 * Create a new main loop source that is used to watch
723 * for the I/O condition @condition. Typically the
724 * qio_channel_add_watch() method would be used instead
725 * of this, since it directly attaches a callback to
728 * Returns: the new main loop source.
730 GSource
*qio_channel_create_watch(QIOChannel
*ioc
,
731 GIOCondition condition
);
734 * qio_channel_add_watch:
735 * @ioc: the channel object
736 * @condition: the I/O condition to monitor
737 * @func: callback to invoke when the source becomes ready
738 * @user_data: opaque data to pass to @func
739 * @notify: callback to free @user_data
741 * Create a new main loop source that is used to watch
742 * for the I/O condition @condition. The callback @func
743 * will be registered against the source, to be invoked
744 * when the source becomes ready. The optional @user_data
745 * will be passed to @func when it is invoked. The @notify
746 * callback will be used to free @user_data when the
749 * The returned source ID can be used with g_source_remove()
750 * to remove and free the source when no longer required.
751 * Alternatively the @func callback can return a FALSE
754 * Returns: the source ID
756 guint
qio_channel_add_watch(QIOChannel
*ioc
,
757 GIOCondition condition
,
760 GDestroyNotify notify
);
763 * qio_channel_add_watch_full:
764 * @ioc: the channel object
765 * @condition: the I/O condition to monitor
766 * @func: callback to invoke when the source becomes ready
767 * @user_data: opaque data to pass to @func
768 * @notify: callback to free @user_data
769 * @context: the context to run the watch source
771 * Similar as qio_channel_add_watch(), but allows to specify context
772 * to run the watch source.
774 * Returns: the source ID
776 guint
qio_channel_add_watch_full(QIOChannel
*ioc
,
777 GIOCondition condition
,
780 GDestroyNotify notify
,
781 GMainContext
*context
);
784 * qio_channel_add_watch_source:
785 * @ioc: the channel object
786 * @condition: the I/O condition to monitor
787 * @func: callback to invoke when the source becomes ready
788 * @user_data: opaque data to pass to @func
789 * @notify: callback to free @user_data
790 * @context: gcontext to bind the source to
792 * Similar as qio_channel_add_watch(), but allows to specify context
793 * to run the watch source, meanwhile return the GSource object
794 * instead of tag ID, with the GSource referenced already.
796 * Note: callers is responsible to unref the source when not needed.
798 * Returns: the source pointer
800 GSource
*qio_channel_add_watch_source(QIOChannel
*ioc
,
801 GIOCondition condition
,
804 GDestroyNotify notify
,
805 GMainContext
*context
);
809 * @ioc: the channel object
810 * @condition: the I/O condition to wait for
812 * Yields execution from the current coroutine until the condition
813 * indicated by @condition becomes available. @condition must
814 * be either %G_IO_IN or %G_IO_OUT; it cannot contain both. In
815 * addition, no two coroutine can be waiting on the same condition
816 * and channel at the same time.
818 * This must only be called from coroutine context. It is safe to
819 * reenter the coroutine externally while it is waiting; in this
820 * case the function will return even if @condition is not yet
823 void coroutine_fn
qio_channel_yield(QIOChannel
*ioc
,
824 GIOCondition condition
);
827 * qio_channel_wake_read:
828 * @ioc: the channel object
830 * If qio_channel_yield() is currently waiting for the channel to become
831 * readable, interrupt it and reenter immediately. This function is safe to call
834 void qio_channel_wake_read(QIOChannel
*ioc
);
838 * @ioc: the channel object
839 * @condition: the I/O condition to wait for
841 * Block execution from the current thread until
842 * the condition indicated by @condition becomes
845 * This will enter a nested event loop to perform
848 void qio_channel_wait(QIOChannel
*ioc
,
849 GIOCondition condition
);
852 * qio_channel_set_aio_fd_handler:
853 * @ioc: the channel object
854 * @read_ctx: the AioContext to set the read handler on or NULL
855 * @io_read: the read handler
856 * @write_ctx: the AioContext to set the write handler on or NULL
857 * @io_write: the write handler
858 * @opaque: the opaque value passed to the handler
860 * This is used internally by qio_channel_yield(). It can
861 * be used by channel implementations to forward the handlers
862 * to another channel (e.g. from #QIOChannelTLS to the
863 * underlying socket).
865 * When @read_ctx is NULL, don't touch the read handler. When @write_ctx is
866 * NULL, don't touch the write handler. Note that setting the read handler
867 * clears the write handler, and vice versa, if they share the same AioContext.
868 * Therefore the caller must pass both handlers together when sharing the same
871 void qio_channel_set_aio_fd_handler(QIOChannel
*ioc
,
872 AioContext
*read_ctx
,
874 AioContext
*write_ctx
,
879 * qio_channel_readv_full_all_eof:
880 * @ioc: the channel object
881 * @iov: the array of memory regions to read data to
882 * @niov: the length of the @iov array
883 * @fds: an array of file handles to read
884 * @nfds: number of file handles in @fds
885 * @errp: pointer to a NULL-initialized error object
888 * Performs same function as qio_channel_readv_all_eof.
889 * Additionally, attempts to read file descriptors shared
890 * over the channel. The function will wait for all
891 * requested data to be read, yielding from the current
892 * coroutine if required. data refers to both file
893 * descriptors and the iovs.
895 * Returns: 1 if all bytes were read, 0 if end-of-file
896 * occurs without data, or -1 on error
899 int coroutine_mixed_fn
qio_channel_readv_full_all_eof(QIOChannel
*ioc
,
900 const struct iovec
*iov
,
902 int **fds
, size_t *nfds
,
906 * qio_channel_readv_full_all:
907 * @ioc: the channel object
908 * @iov: the array of memory regions to read data to
909 * @niov: the length of the @iov array
910 * @fds: an array of file handles to read
911 * @nfds: number of file handles in @fds
912 * @errp: pointer to a NULL-initialized error object
915 * Performs same function as qio_channel_readv_all_eof.
916 * Additionally, attempts to read file descriptors shared
917 * over the channel. The function will wait for all
918 * requested data to be read, yielding from the current
919 * coroutine if required. data refers to both file
920 * descriptors and the iovs.
922 * Returns: 0 if all bytes were read, or -1 on error
925 int coroutine_mixed_fn
qio_channel_readv_full_all(QIOChannel
*ioc
,
926 const struct iovec
*iov
,
928 int **fds
, size_t *nfds
,
932 * qio_channel_writev_full_all:
933 * @ioc: the channel object
934 * @iov: the array of memory regions to write data from
935 * @niov: the length of the @iov array
936 * @fds: an array of file handles to send
937 * @nfds: number of file handles in @fds
938 * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*)
939 * @errp: pointer to a NULL-initialized error object
942 * Behaves like qio_channel_writev_full but will attempt
943 * to send all data passed (file handles and memory regions).
944 * The function will wait for all requested data
945 * to be written, yielding from the current coroutine
948 * If QIO_CHANNEL_WRITE_FLAG_ZERO_COPY is passed in flags,
949 * instead of waiting for all requested data to be written,
950 * this function will wait until it's all queued for writing.
951 * In this case, if the buffer gets changed between queueing and
952 * sending, the updated buffer will be sent. If this is not a
953 * desired behavior, it's suggested to call qio_channel_flush()
954 * before reusing the buffer.
956 * Returns: 0 if all bytes were written, or -1 on error
959 int coroutine_mixed_fn
qio_channel_writev_full_all(QIOChannel
*ioc
,
960 const struct iovec
*iov
,
962 int *fds
, size_t nfds
,
963 int flags
, Error
**errp
);
967 * @ioc: the channel object
968 * @errp: pointer to a NULL-initialized error object
970 * Will block until every packet queued with
971 * qio_channel_writev_full() + QIO_CHANNEL_WRITE_FLAG_ZERO_COPY
972 * is sent, or return in case of any error.
974 * If not implemented, acts as a no-op, and returns 0.
976 * Returns -1 if any error is found,
977 * 1 if every send failed to use zero copy.
981 int qio_channel_flush(QIOChannel
*ioc
,
984 #endif /* QIO_CHANNEL_H */