xref: /openbmc/qemu/include/io/channel.h (revision 5f88dd43)
1 /*
2  * QEMU I/O channels
3  *
4  * Copyright (c) 2015 Red Hat, Inc.
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 #ifndef QIO_CHANNEL_H
22 #define QIO_CHANNEL_H
23 
24 #include "qom/object.h"
25 #include "qemu/coroutine-core.h"
26 #include "block/aio.h"
27 
28 #define TYPE_QIO_CHANNEL "qio-channel"
29 OBJECT_DECLARE_TYPE(QIOChannel, QIOChannelClass,
30                     QIO_CHANNEL)
31 
32 
33 #define QIO_CHANNEL_ERR_BLOCK -2
34 
35 #define QIO_CHANNEL_WRITE_FLAG_ZERO_COPY 0x1
36 
37 #define QIO_CHANNEL_READ_FLAG_MSG_PEEK 0x1
38 
39 typedef enum QIOChannelFeature QIOChannelFeature;
40 
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 };
48 
49 
50 typedef enum QIOChannelShutdown QIOChannelShutdown;
51 
52 enum QIOChannelShutdown {
53     QIO_CHANNEL_SHUTDOWN_READ = 1,
54     QIO_CHANNEL_SHUTDOWN_WRITE = 2,
55     QIO_CHANNEL_SHUTDOWN_BOTH = 3,
56 };
57 
58 typedef gboolean (*QIOChannelFunc)(QIOChannel *ioc,
59                                    GIOCondition condition,
60                                    gpointer data);
61 
62 /**
63  * QIOChannel:
64  *
65  * The QIOChannel defines the core API for a generic I/O channel
66  * class hierarchy. It is inspired by GIOChannel, but has the
67  * following differences
68  *
69  *  - Use QOM to properly support arbitrary subclassing
70  *  - Support use of iovecs for efficient I/O with multiple blocks
71  *  - None of the character set translation, binary data exclusively
72  *  - Direct support for QEMU Error object reporting
73  *  - File descriptor passing
74  *
75  * This base class is abstract so cannot be instantiated. There
76  * will be subclasses for dealing with sockets, files, and higher
77  * level protocols such as TLS, WebSocket, etc.
78  */
79 
80 struct QIOChannel {
81     Object parent;
82     unsigned int features; /* bitmask of QIOChannelFeatures */
83     char *name;
84     AioContext *read_ctx;
85     Coroutine *read_coroutine;
86     AioContext *write_ctx;
87     Coroutine *write_coroutine;
88     bool follow_coroutine_ctx;
89 #ifdef _WIN32
90     HANDLE event; /* For use with GSource on Win32 */
91 #endif
92 };
93 
94 /**
95  * QIOChannelClass:
96  *
97  * This class defines the contract that all subclasses
98  * must follow to provide specific channel implementations.
99  * The first five callbacks are mandatory to support, others
100  * provide additional optional features.
101  *
102  * Consult the corresponding public API docs for a description
103  * of the semantics of each callback. io_shutdown in particular
104  * must be thread-safe, terminate quickly and must not block.
105  */
106 struct QIOChannelClass {
107     ObjectClass parent;
108 
109     /* Mandatory callbacks */
110     ssize_t (*io_writev)(QIOChannel *ioc,
111                          const struct iovec *iov,
112                          size_t niov,
113                          int *fds,
114                          size_t nfds,
115                          int flags,
116                          Error **errp);
117     ssize_t (*io_readv)(QIOChannel *ioc,
118                         const struct iovec *iov,
119                         size_t niov,
120                         int **fds,
121                         size_t *nfds,
122                         int flags,
123                         Error **errp);
124     int (*io_close)(QIOChannel *ioc,
125                     Error **errp);
126     GSource * (*io_create_watch)(QIOChannel *ioc,
127                                  GIOCondition condition);
128     int (*io_set_blocking)(QIOChannel *ioc,
129                            bool enabled,
130                            Error **errp);
131 
132     /* Optional callbacks */
133     int (*io_shutdown)(QIOChannel *ioc,
134                        QIOChannelShutdown how,
135                        Error **errp);
136     void (*io_set_cork)(QIOChannel *ioc,
137                         bool enabled);
138     void (*io_set_delay)(QIOChannel *ioc,
139                          bool enabled);
140     off_t (*io_seek)(QIOChannel *ioc,
141                      off_t offset,
142                      int whence,
143                      Error **errp);
144     void (*io_set_aio_fd_handler)(QIOChannel *ioc,
145                                   AioContext *read_ctx,
146                                   IOHandler *io_read,
147                                   AioContext *write_ctx,
148                                   IOHandler *io_write,
149                                   void *opaque);
150     int (*io_flush)(QIOChannel *ioc,
151                     Error **errp);
152 };
153 
154 /* General I/O handling functions */
155 
156 /**
157  * qio_channel_has_feature:
158  * @ioc: the channel object
159  * @feature: the feature to check support of
160  *
161  * Determine whether the channel implementation supports
162  * the optional feature named in @feature.
163  *
164  * Returns: true if supported, false otherwise.
165  */
166 bool qio_channel_has_feature(QIOChannel *ioc,
167                              QIOChannelFeature feature);
168 
169 /**
170  * qio_channel_set_feature:
171  * @ioc: the channel object
172  * @feature: the feature to set support for
173  *
174  * Add channel support for the feature named in @feature.
175  */
176 void qio_channel_set_feature(QIOChannel *ioc,
177                              QIOChannelFeature feature);
178 
179 /**
180  * qio_channel_set_name:
181  * @ioc: the channel object
182  * @name: the name of the channel
183  *
184  * Sets the name of the channel, which serves as an aid
185  * to debugging. The name is used when creating GSource
186  * watches for this channel.
187  */
188 void qio_channel_set_name(QIOChannel *ioc,
189                           const char *name);
190 
191 /**
192  * qio_channel_readv_full:
193  * @ioc: the channel object
194  * @iov: the array of memory regions to read data into
195  * @niov: the length of the @iov array
196  * @fds: pointer to an array that will received file handles
197  * @nfds: pointer filled with number of elements in @fds on return
198  * @flags: read flags (QIO_CHANNEL_READ_FLAG_*)
199  * @errp: pointer to a NULL-initialized error object
200  *
201  * Read data from the IO channel, storing it in the
202  * memory regions referenced by @iov. Each element
203  * in the @iov will be fully populated with data
204  * before the next one is used. The @niov parameter
205  * specifies the total number of elements in @iov.
206  *
207  * It is not required for all @iov to be filled with
208  * data. If the channel is in blocking mode, at least
209  * one byte of data will be read, but no more is
210  * guaranteed. If the channel is non-blocking and no
211  * data is available, it will return QIO_CHANNEL_ERR_BLOCK
212  *
213  * If the channel has passed any file descriptors,
214  * the @fds array pointer will be allocated and
215  * the elements filled with the received file
216  * descriptors. The @nfds pointer will be updated
217  * to indicate the size of the @fds array that
218  * was allocated. It is the callers responsibility
219  * to call close() on each file descriptor and to
220  * call g_free() on the array pointer in @fds.
221  *
222  * It is an error to pass a non-NULL @fds parameter
223  * unless qio_channel_has_feature() returns a true
224  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
225  *
226  * Returns: the number of bytes read, or -1 on error,
227  * or QIO_CHANNEL_ERR_BLOCK if no data is available
228  * and the channel is non-blocking
229  */
230 ssize_t qio_channel_readv_full(QIOChannel *ioc,
231                                const struct iovec *iov,
232                                size_t niov,
233                                int **fds,
234                                size_t *nfds,
235                                int flags,
236                                Error **errp);
237 
238 
239 /**
240  * qio_channel_writev_full:
241  * @ioc: the channel object
242  * @iov: the array of memory regions to write data from
243  * @niov: the length of the @iov array
244  * @fds: an array of file handles to send
245  * @nfds: number of file handles in @fds
246  * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*)
247  * @errp: pointer to a NULL-initialized error object
248  *
249  * Write data to the IO channel, reading it from the
250  * memory regions referenced by @iov. Each element
251  * in the @iov will be fully sent, before the next
252  * one is used. The @niov parameter specifies the
253  * total number of elements in @iov.
254  *
255  * It is not required for all @iov data to be fully
256  * sent. If the channel is in blocking mode, at least
257  * one byte of data will be sent, but no more is
258  * guaranteed. If the channel is non-blocking and no
259  * data can be sent, it will return QIO_CHANNEL_ERR_BLOCK
260  *
261  * If there are file descriptors to send, the @fds
262  * array should be non-NULL and provide the handles.
263  * All file descriptors will be sent if at least one
264  * byte of data was sent.
265  *
266  * It is an error to pass a non-NULL @fds parameter
267  * unless qio_channel_has_feature() returns a true
268  * value for the QIO_CHANNEL_FEATURE_FD_PASS constant.
269  *
270  * Returns: the number of bytes sent, or -1 on error,
271  * or QIO_CHANNEL_ERR_BLOCK if no data is can be sent
272  * and the channel is non-blocking
273  */
274 ssize_t qio_channel_writev_full(QIOChannel *ioc,
275                                 const struct iovec *iov,
276                                 size_t niov,
277                                 int *fds,
278                                 size_t nfds,
279                                 int flags,
280                                 Error **errp);
281 
282 /**
283  * qio_channel_readv_all_eof:
284  * @ioc: the channel object
285  * @iov: the array of memory regions to read data into
286  * @niov: the length of the @iov array
287  * @errp: pointer to a NULL-initialized error object
288  *
289  * Read data from the IO channel, storing it in the
290  * memory regions referenced by @iov. Each element
291  * in the @iov will be fully populated with data
292  * before the next one is used. The @niov parameter
293  * specifies the total number of elements in @iov.
294  *
295  * The function will wait for all requested data
296  * to be read, yielding from the current coroutine
297  * if required.
298  *
299  * If end-of-file occurs before any data is read,
300  * no error is reported; otherwise, if it occurs
301  * before all requested data has been read, an error
302  * will be reported.
303  *
304  * Returns: 1 if all bytes were read, 0 if end-of-file
305  *          occurs without data, or -1 on error
306  */
307 int coroutine_mixed_fn qio_channel_readv_all_eof(QIOChannel *ioc,
308                                                  const struct iovec *iov,
309                                                  size_t niov,
310                                                  Error **errp);
311 
312 /**
313  * qio_channel_readv_all:
314  * @ioc: the channel object
315  * @iov: the array of memory regions to read data into
316  * @niov: the length of the @iov array
317  * @errp: pointer to a NULL-initialized error object
318  *
319  * Read data from the IO channel, storing it in the
320  * memory regions referenced by @iov. Each element
321  * in the @iov will be fully populated with data
322  * before the next one is used. The @niov parameter
323  * specifies the total number of elements in @iov.
324  *
325  * The function will wait for all requested data
326  * to be read, yielding from the current coroutine
327  * if required.
328  *
329  * If end-of-file occurs before all requested data
330  * has been read, an error will be reported.
331  *
332  * Returns: 0 if all bytes were read, or -1 on error
333  */
334 int coroutine_mixed_fn qio_channel_readv_all(QIOChannel *ioc,
335                                              const struct iovec *iov,
336                                              size_t niov,
337                                              Error **errp);
338 
339 
340 /**
341  * qio_channel_writev_all:
342  * @ioc: the channel object
343  * @iov: the array of memory regions to write data from
344  * @niov: the length of the @iov array
345  * @errp: pointer to a NULL-initialized error object
346  *
347  * Write data to the IO channel, reading it from the
348  * memory regions referenced by @iov. Each element
349  * in the @iov will be fully sent, before the next
350  * one is used. The @niov parameter specifies the
351  * total number of elements in @iov.
352  *
353  * The function will wait for all requested data
354  * to be written, yielding from the current coroutine
355  * if required.
356  *
357  * Returns: 0 if all bytes were written, or -1 on error
358  */
359 int coroutine_mixed_fn qio_channel_writev_all(QIOChannel *ioc,
360                                               const struct iovec *iov,
361                                               size_t niov,
362                                               Error **errp);
363 
364 /**
365  * qio_channel_readv:
366  * @ioc: the channel object
367  * @iov: the array of memory regions to read data into
368  * @niov: the length of the @iov array
369  * @errp: pointer to a NULL-initialized error object
370  *
371  * Behaves as qio_channel_readv_full() but does not support
372  * receiving of file handles.
373  */
374 ssize_t qio_channel_readv(QIOChannel *ioc,
375                           const struct iovec *iov,
376                           size_t niov,
377                           Error **errp);
378 
379 /**
380  * qio_channel_writev:
381  * @ioc: the channel object
382  * @iov: the array of memory regions to write data from
383  * @niov: the length of the @iov array
384  * @errp: pointer to a NULL-initialized error object
385  *
386  * Behaves as qio_channel_writev_full() but does not support
387  * sending of file handles.
388  */
389 ssize_t qio_channel_writev(QIOChannel *ioc,
390                            const struct iovec *iov,
391                            size_t niov,
392                            Error **errp);
393 
394 /**
395  * qio_channel_read:
396  * @ioc: the channel object
397  * @buf: the memory region to read data into
398  * @buflen: the length of @buf
399  * @errp: pointer to a NULL-initialized error object
400  *
401  * Behaves as qio_channel_readv_full() but does not support
402  * receiving of file handles, and only supports reading into
403  * a single memory region.
404  */
405 ssize_t qio_channel_read(QIOChannel *ioc,
406                          char *buf,
407                          size_t buflen,
408                          Error **errp);
409 
410 /**
411  * qio_channel_write:
412  * @ioc: the channel object
413  * @buf: the memory regions to send data from
414  * @buflen: the length of @buf
415  * @errp: pointer to a NULL-initialized error object
416  *
417  * Behaves as qio_channel_writev_full() but does not support
418  * sending of file handles, and only supports writing from a
419  * single memory region.
420  */
421 ssize_t qio_channel_write(QIOChannel *ioc,
422                           const char *buf,
423                           size_t buflen,
424                           Error **errp);
425 
426 /**
427  * qio_channel_read_all_eof:
428  * @ioc: the channel object
429  * @buf: the memory region to read data into
430  * @buflen: the number of bytes to @buf
431  * @errp: pointer to a NULL-initialized error object
432  *
433  * Reads @buflen bytes into @buf, possibly blocking or (if the
434  * channel is non-blocking) yielding from the current coroutine
435  * multiple times until the entire content is read. If end-of-file
436  * occurs immediately it is not an error, but if it occurs after
437  * data has been read it will return an error rather than a
438  * short-read. Otherwise behaves as qio_channel_read().
439  *
440  * Returns: 1 if all bytes were read, 0 if end-of-file occurs
441  *          without data, or -1 on error
442  */
443 int coroutine_mixed_fn qio_channel_read_all_eof(QIOChannel *ioc,
444                                                 char *buf,
445                                                 size_t buflen,
446                                                 Error **errp);
447 
448 /**
449  * qio_channel_read_all:
450  * @ioc: the channel object
451  * @buf: the memory region to read data into
452  * @buflen: the number of bytes to @buf
453  * @errp: pointer to a NULL-initialized error object
454  *
455  * Reads @buflen bytes into @buf, possibly blocking or (if the
456  * channel is non-blocking) yielding from the current coroutine
457  * multiple times until the entire content is read. If end-of-file
458  * occurs it will return an error rather than a short-read. Otherwise
459  * behaves as qio_channel_read().
460  *
461  * Returns: 0 if all bytes were read, or -1 on error
462  */
463 int coroutine_mixed_fn qio_channel_read_all(QIOChannel *ioc,
464                                             char *buf,
465                                             size_t buflen,
466                                             Error **errp);
467 
468 /**
469  * qio_channel_write_all:
470  * @ioc: the channel object
471  * @buf: the memory region to write data into
472  * @buflen: the number of bytes to @buf
473  * @errp: pointer to a NULL-initialized error object
474  *
475  * Writes @buflen bytes from @buf, possibly blocking or (if the
476  * channel is non-blocking) yielding from the current coroutine
477  * multiple times until the entire content is written.  Otherwise
478  * behaves as qio_channel_write().
479  *
480  * Returns: 0 if all bytes were written, or -1 on error
481  */
482 int coroutine_mixed_fn qio_channel_write_all(QIOChannel *ioc,
483                                              const char *buf,
484                                              size_t buflen,
485                                              Error **errp);
486 
487 /**
488  * qio_channel_set_blocking:
489  * @ioc: the channel object
490  * @enabled: the blocking flag state
491  * @errp: pointer to a NULL-initialized error object
492  *
493  * If @enabled is true, then the channel is put into
494  * blocking mode, otherwise it will be non-blocking.
495  *
496  * In non-blocking mode, read/write operations may
497  * return QIO_CHANNEL_ERR_BLOCK if they would otherwise
498  * block on I/O
499  */
500 int qio_channel_set_blocking(QIOChannel *ioc,
501                              bool enabled,
502                              Error **errp);
503 
504 /**
505  * qio_channel_set_follow_coroutine_ctx:
506  * @ioc: the channel object
507  * @enabled: whether or not to follow the coroutine's AioContext
508  *
509  * If @enabled is true, calls to qio_channel_yield() use the current
510  * coroutine's AioContext. Usually this is desirable.
511  *
512  * If @enabled is false, calls to qio_channel_yield() use the global iohandler
513  * AioContext. This is may be used by coroutines that run in the main loop and
514  * do not wish to respond to I/O during nested event loops. This is the
515  * default for compatibility with code that is not aware of AioContexts.
516  */
517 void qio_channel_set_follow_coroutine_ctx(QIOChannel *ioc, bool enabled);
518 
519 /**
520  * qio_channel_close:
521  * @ioc: the channel object
522  * @errp: pointer to a NULL-initialized error object
523  *
524  * Close the channel, flushing any pending I/O
525  *
526  * Returns: 0 on success, -1 on error
527  */
528 int qio_channel_close(QIOChannel *ioc,
529                       Error **errp);
530 
531 /**
532  * qio_channel_shutdown:
533  * @ioc: the channel object
534  * @how: the direction to shutdown
535  * @errp: pointer to a NULL-initialized error object
536  *
537  * Shutdowns transmission and/or receiving of data
538  * without closing the underlying transport.
539  *
540  * Not all implementations will support this facility,
541  * so may report an error. To avoid errors, the
542  * caller may check for the feature flag
543  * QIO_CHANNEL_FEATURE_SHUTDOWN prior to calling
544  * this method.
545  *
546  * This function is thread-safe, terminates quickly and does not block.
547  *
548  * Returns: 0 on success, -1 on error
549  */
550 int qio_channel_shutdown(QIOChannel *ioc,
551                          QIOChannelShutdown how,
552                          Error **errp);
553 
554 /**
555  * qio_channel_set_delay:
556  * @ioc: the channel object
557  * @enabled: the new flag state
558  *
559  * Controls whether the underlying transport is
560  * permitted to delay writes in order to merge
561  * small packets. If @enabled is true, then the
562  * writes may be delayed in order to opportunistically
563  * merge small packets into larger ones. If @enabled
564  * is false, writes are dispatched immediately with
565  * no delay.
566  *
567  * When @enabled is false, applications may wish to
568  * use the qio_channel_set_cork() method to explicitly
569  * control write merging.
570  *
571  * On channels which are backed by a socket, this
572  * API corresponds to the inverse of TCP_NODELAY flag,
573  * controlling whether the Nagle algorithm is active.
574  *
575  * This setting is merely a hint, so implementations are
576  * free to ignore this without it being considered an
577  * error.
578  */
579 void qio_channel_set_delay(QIOChannel *ioc,
580                            bool enabled);
581 
582 /**
583  * qio_channel_set_cork:
584  * @ioc: the channel object
585  * @enabled: the new flag state
586  *
587  * Controls whether the underlying transport is
588  * permitted to dispatch data that is written.
589  * If @enabled is true, then any data written will
590  * be queued in local buffers until @enabled is
591  * set to false once again.
592  *
593  * This feature is typically used when the automatic
594  * write coalescing facility is disabled via the
595  * qio_channel_set_delay() method.
596  *
597  * On channels which are backed by a socket, this
598  * API corresponds to the TCP_CORK flag.
599  *
600  * This setting is merely a hint, so implementations are
601  * free to ignore this without it being considered an
602  * error.
603  */
604 void qio_channel_set_cork(QIOChannel *ioc,
605                           bool enabled);
606 
607 
608 /**
609  * qio_channel_seek:
610  * @ioc: the channel object
611  * @offset: the position to seek to, relative to @whence
612  * @whence: one of the (POSIX) SEEK_* constants listed below
613  * @errp: pointer to a NULL-initialized error object
614  *
615  * Moves the current I/O position within the channel
616  * @ioc, to be @offset. The value of @offset is
617  * interpreted relative to @whence:
618  *
619  * SEEK_SET - the position is set to @offset bytes
620  * SEEK_CUR - the position is moved by @offset bytes
621  * SEEK_END - the position is set to end of the file plus @offset bytes
622  *
623  * Not all implementations will support this facility,
624  * so may report an error.
625  *
626  * Returns: the new position on success, (off_t)-1 on failure
627  */
628 off_t qio_channel_io_seek(QIOChannel *ioc,
629                           off_t offset,
630                           int whence,
631                           Error **errp);
632 
633 
634 /**
635  * qio_channel_create_watch:
636  * @ioc: the channel object
637  * @condition: the I/O condition to monitor
638  *
639  * Create a new main loop source that is used to watch
640  * for the I/O condition @condition. Typically the
641  * qio_channel_add_watch() method would be used instead
642  * of this, since it directly attaches a callback to
643  * the source
644  *
645  * Returns: the new main loop source.
646  */
647 GSource *qio_channel_create_watch(QIOChannel *ioc,
648                                   GIOCondition condition);
649 
650 /**
651  * qio_channel_add_watch:
652  * @ioc: the channel object
653  * @condition: the I/O condition to monitor
654  * @func: callback to invoke when the source becomes ready
655  * @user_data: opaque data to pass to @func
656  * @notify: callback to free @user_data
657  *
658  * Create a new main loop source that is used to watch
659  * for the I/O condition @condition. The callback @func
660  * will be registered against the source, to be invoked
661  * when the source becomes ready. The optional @user_data
662  * will be passed to @func when it is invoked. The @notify
663  * callback will be used to free @user_data when the
664  * watch is deleted
665  *
666  * The returned source ID can be used with g_source_remove()
667  * to remove and free the source when no longer required.
668  * Alternatively the @func callback can return a FALSE
669  * value.
670  *
671  * Returns: the source ID
672  */
673 guint qio_channel_add_watch(QIOChannel *ioc,
674                             GIOCondition condition,
675                             QIOChannelFunc func,
676                             gpointer user_data,
677                             GDestroyNotify notify);
678 
679 /**
680  * qio_channel_add_watch_full:
681  * @ioc: the channel object
682  * @condition: the I/O condition to monitor
683  * @func: callback to invoke when the source becomes ready
684  * @user_data: opaque data to pass to @func
685  * @notify: callback to free @user_data
686  * @context: the context to run the watch source
687  *
688  * Similar as qio_channel_add_watch(), but allows to specify context
689  * to run the watch source.
690  *
691  * Returns: the source ID
692  */
693 guint qio_channel_add_watch_full(QIOChannel *ioc,
694                                  GIOCondition condition,
695                                  QIOChannelFunc func,
696                                  gpointer user_data,
697                                  GDestroyNotify notify,
698                                  GMainContext *context);
699 
700 /**
701  * qio_channel_add_watch_source:
702  * @ioc: the channel object
703  * @condition: the I/O condition to monitor
704  * @func: callback to invoke when the source becomes ready
705  * @user_data: opaque data to pass to @func
706  * @notify: callback to free @user_data
707  * @context: gcontext to bind the source to
708  *
709  * Similar as qio_channel_add_watch(), but allows to specify context
710  * to run the watch source, meanwhile return the GSource object
711  * instead of tag ID, with the GSource referenced already.
712  *
713  * Note: callers is responsible to unref the source when not needed.
714  *
715  * Returns: the source pointer
716  */
717 GSource *qio_channel_add_watch_source(QIOChannel *ioc,
718                                       GIOCondition condition,
719                                       QIOChannelFunc func,
720                                       gpointer user_data,
721                                       GDestroyNotify notify,
722                                       GMainContext *context);
723 
724 /**
725  * qio_channel_yield:
726  * @ioc: the channel object
727  * @condition: the I/O condition to wait for
728  *
729  * Yields execution from the current coroutine until the condition
730  * indicated by @condition becomes available.  @condition must
731  * be either %G_IO_IN or %G_IO_OUT; it cannot contain both.  In
732  * addition, no two coroutine can be waiting on the same condition
733  * and channel at the same time.
734  *
735  * This must only be called from coroutine context. It is safe to
736  * reenter the coroutine externally while it is waiting; in this
737  * case the function will return even if @condition is not yet
738  * available.
739  */
740 void coroutine_fn qio_channel_yield(QIOChannel *ioc,
741                                     GIOCondition condition);
742 
743 /**
744  * qio_channel_wake_read:
745  * @ioc: the channel object
746  *
747  * If qio_channel_yield() is currently waiting for the channel to become
748  * readable, interrupt it and reenter immediately. This function is safe to call
749  * from any thread.
750  */
751 void qio_channel_wake_read(QIOChannel *ioc);
752 
753 /**
754  * qio_channel_wait:
755  * @ioc: the channel object
756  * @condition: the I/O condition to wait for
757  *
758  * Block execution from the current thread until
759  * the condition indicated by @condition becomes
760  * available.
761  *
762  * This will enter a nested event loop to perform
763  * the wait.
764  */
765 void qio_channel_wait(QIOChannel *ioc,
766                       GIOCondition condition);
767 
768 /**
769  * qio_channel_set_aio_fd_handler:
770  * @ioc: the channel object
771  * @read_ctx: the AioContext to set the read handler on or NULL
772  * @io_read: the read handler
773  * @write_ctx: the AioContext to set the write handler on or NULL
774  * @io_write: the write handler
775  * @opaque: the opaque value passed to the handler
776  *
777  * This is used internally by qio_channel_yield().  It can
778  * be used by channel implementations to forward the handlers
779  * to another channel (e.g. from #QIOChannelTLS to the
780  * underlying socket).
781  *
782  * When @read_ctx is NULL, don't touch the read handler. When @write_ctx is
783  * NULL, don't touch the write handler. Note that setting the read handler
784  * clears the write handler, and vice versa, if they share the same AioContext.
785  * Therefore the caller must pass both handlers together when sharing the same
786  * AioContext.
787  */
788 void qio_channel_set_aio_fd_handler(QIOChannel *ioc,
789                                     AioContext *read_ctx,
790                                     IOHandler *io_read,
791                                     AioContext *write_ctx,
792                                     IOHandler *io_write,
793                                     void *opaque);
794 
795 /**
796  * qio_channel_readv_full_all_eof:
797  * @ioc: the channel object
798  * @iov: the array of memory regions to read data to
799  * @niov: the length of the @iov array
800  * @fds: an array of file handles to read
801  * @nfds: number of file handles in @fds
802  * @errp: pointer to a NULL-initialized error object
803  *
804  *
805  * Performs same function as qio_channel_readv_all_eof.
806  * Additionally, attempts to read file descriptors shared
807  * over the channel. The function will wait for all
808  * requested data to be read, yielding from the current
809  * coroutine if required. data refers to both file
810  * descriptors and the iovs.
811  *
812  * Returns: 1 if all bytes were read, 0 if end-of-file
813  *          occurs without data, or -1 on error
814  */
815 
816 int coroutine_mixed_fn qio_channel_readv_full_all_eof(QIOChannel *ioc,
817                                                       const struct iovec *iov,
818                                                       size_t niov,
819                                                       int **fds, size_t *nfds,
820                                                       Error **errp);
821 
822 /**
823  * qio_channel_readv_full_all:
824  * @ioc: the channel object
825  * @iov: the array of memory regions to read data to
826  * @niov: the length of the @iov array
827  * @fds: an array of file handles to read
828  * @nfds: number of file handles in @fds
829  * @errp: pointer to a NULL-initialized error object
830  *
831  *
832  * Performs same function as qio_channel_readv_all_eof.
833  * Additionally, attempts to read file descriptors shared
834  * over the channel. The function will wait for all
835  * requested data to be read, yielding from the current
836  * coroutine if required. data refers to both file
837  * descriptors and the iovs.
838  *
839  * Returns: 0 if all bytes were read, or -1 on error
840  */
841 
842 int coroutine_mixed_fn qio_channel_readv_full_all(QIOChannel *ioc,
843                                                   const struct iovec *iov,
844                                                   size_t niov,
845                                                   int **fds, size_t *nfds,
846                                                   Error **errp);
847 
848 /**
849  * qio_channel_writev_full_all:
850  * @ioc: the channel object
851  * @iov: the array of memory regions to write data from
852  * @niov: the length of the @iov array
853  * @fds: an array of file handles to send
854  * @nfds: number of file handles in @fds
855  * @flags: write flags (QIO_CHANNEL_WRITE_FLAG_*)
856  * @errp: pointer to a NULL-initialized error object
857  *
858  *
859  * Behaves like qio_channel_writev_full but will attempt
860  * to send all data passed (file handles and memory regions).
861  * The function will wait for all requested data
862  * to be written, yielding from the current coroutine
863  * if required.
864  *
865  * If QIO_CHANNEL_WRITE_FLAG_ZERO_COPY is passed in flags,
866  * instead of waiting for all requested data to be written,
867  * this function will wait until it's all queued for writing.
868  * In this case, if the buffer gets changed between queueing and
869  * sending, the updated buffer will be sent. If this is not a
870  * desired behavior, it's suggested to call qio_channel_flush()
871  * before reusing the buffer.
872  *
873  * Returns: 0 if all bytes were written, or -1 on error
874  */
875 
876 int coroutine_mixed_fn qio_channel_writev_full_all(QIOChannel *ioc,
877                                                    const struct iovec *iov,
878                                                    size_t niov,
879                                                    int *fds, size_t nfds,
880                                                    int flags, Error **errp);
881 
882 /**
883  * qio_channel_flush:
884  * @ioc: the channel object
885  * @errp: pointer to a NULL-initialized error object
886  *
887  * Will block until every packet queued with
888  * qio_channel_writev_full() + QIO_CHANNEL_WRITE_FLAG_ZERO_COPY
889  * is sent, or return in case of any error.
890  *
891  * If not implemented, acts as a no-op, and returns 0.
892  *
893  * Returns -1 if any error is found,
894  *          1 if every send failed to use zero copy.
895  *          0 otherwise.
896  */
897 
898 int qio_channel_flush(QIOChannel *ioc,
899                       Error **errp);
900 
901 #endif /* QIO_CHANNEL_H */
902