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