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