usb-bsd: convert to QOM
[qemu.git] / main-loop.h
1 /*
2 * QEMU System Emulator
3 *
4 * Copyright (c) 2003-2008 Fabrice Bellard
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24
25 #ifndef QEMU_MAIN_LOOP_H
26 #define QEMU_MAIN_LOOP_H 1
27
28 #ifdef SIGRTMIN
29 #define SIG_IPI (SIGRTMIN+4)
30 #else
31 #define SIG_IPI SIGUSR1
32 #endif
33
34 /**
35 * qemu_init_main_loop: Set up the process so that it can run the main loop.
36 *
37 * This includes setting up signal handlers. It should be called before
38 * any other threads are created. In addition, threads other than the
39 * main one should block signals that are trapped by the main loop.
40 * For simplicity, you can consider these signals to be safe: SIGUSR1,
41 * SIGUSR2, thread signals (SIGFPE, SIGILL, SIGSEGV, SIGBUS) and real-time
42 * signals if available. Remember that Windows in practice does not have
43 * signals, though.
44 *
45 * In the case of QEMU tools, this will also start/initialize timers.
46 */
47 int qemu_init_main_loop(void);
48
49 /**
50 * main_loop_init: Initializes main loop
51 *
52 * Internal (but shared for compatibility reasons) initialization routine
53 * for the main loop. This should not be used by applications directly,
54 * use qemu_init_main_loop() instead.
55 *
56 */
57 int main_loop_init(void);
58
59 /**
60 * main_loop_wait: Run one iteration of the main loop.
61 *
62 * If @nonblocking is true, poll for events, otherwise suspend until
63 * one actually occurs. The main loop usually consists of a loop that
64 * repeatedly calls main_loop_wait(false).
65 *
66 * Main loop services include file descriptor callbacks, bottom halves
67 * and timers (defined in qemu-timer.h). Bottom halves are similar to timers
68 * that execute immediately, but have a lower overhead and scheduling them
69 * is wait-free, thread-safe and signal-safe.
70 *
71 * It is sometimes useful to put a whole program in a coroutine. In this
72 * case, the coroutine actually should be started from within the main loop,
73 * so that the main loop can run whenever the coroutine yields. To do this,
74 * you can use a bottom half to enter the coroutine as soon as the main loop
75 * starts:
76 *
77 * void enter_co_bh(void *opaque) {
78 * QEMUCoroutine *co = opaque;
79 * qemu_coroutine_enter(co, NULL);
80 * }
81 *
82 * ...
83 * QEMUCoroutine *co = qemu_coroutine_create(coroutine_entry);
84 * QEMUBH *start_bh = qemu_bh_new(enter_co_bh, co);
85 * qemu_bh_schedule(start_bh);
86 * while (...) {
87 * main_loop_wait(false);
88 * }
89 *
90 * (In the future we may provide a wrapper for this).
91 *
92 * @nonblocking: Whether the caller should block until an event occurs.
93 */
94 int main_loop_wait(int nonblocking);
95
96 /**
97 * qemu_notify_event: Force processing of pending events.
98 *
99 * Similar to signaling a condition variable, qemu_notify_event forces
100 * main_loop_wait to look at pending events and exit. The caller of
101 * main_loop_wait will usually call it again very soon, so qemu_notify_event
102 * also has the side effect of recalculating the sets of file descriptors
103 * that the main loop waits for.
104 *
105 * Calling qemu_notify_event is rarely necessary, because main loop
106 * services (bottom halves and timers) call it themselves. One notable
107 * exception occurs when using qemu_set_fd_handler2 (see below).
108 */
109 void qemu_notify_event(void);
110
111 #ifdef _WIN32
112 /* return TRUE if no sleep should be done afterwards */
113 typedef int PollingFunc(void *opaque);
114
115 /**
116 * qemu_add_polling_cb: Register a Windows-specific polling callback
117 *
118 * Currently, under Windows some events are polled rather than waited for.
119 * Polling callbacks do not ensure that @func is called timely, because
120 * the main loop might wait for an arbitrarily long time. If possible,
121 * you should instead create a separate thread that does a blocking poll
122 * and set a Win32 event object. The event can then be passed to
123 * qemu_add_wait_object.
124 *
125 * Polling callbacks really have nothing Windows specific in them, but
126 * as they are a hack and are currently not necessary under POSIX systems,
127 * they are only available when QEMU is running under Windows.
128 *
129 * @func: The function that does the polling, and returns 1 to force
130 * immediate completion of main_loop_wait.
131 * @opaque: A pointer-size value that is passed to @func.
132 */
133 int qemu_add_polling_cb(PollingFunc *func, void *opaque);
134
135 /**
136 * qemu_del_polling_cb: Unregister a Windows-specific polling callback
137 *
138 * This function removes a callback that was registered with
139 * qemu_add_polling_cb.
140 *
141 * @func: The function that was passed to qemu_add_polling_cb.
142 * @opaque: A pointer-size value that was passed to qemu_add_polling_cb.
143 */
144 void qemu_del_polling_cb(PollingFunc *func, void *opaque);
145
146 /* Wait objects handling */
147 typedef void WaitObjectFunc(void *opaque);
148
149 /**
150 * qemu_add_wait_object: Register a callback for a Windows handle
151 *
152 * Under Windows, the iohandler mechanism can only be used with sockets.
153 * QEMU must use the WaitForMultipleObjects API to wait on other handles.
154 * This function registers a #HANDLE with QEMU, so that it will be included
155 * in the main loop's calls to WaitForMultipleObjects. When the handle
156 * is in a signaled state, QEMU will call @func.
157 *
158 * @handle: The Windows handle to be observed.
159 * @func: A function to be called when @handle is in a signaled state.
160 * @opaque: A pointer-size value that is passed to @func.
161 */
162 int qemu_add_wait_object(HANDLE handle, WaitObjectFunc *func, void *opaque);
163
164 /**
165 * qemu_del_wait_object: Unregister a callback for a Windows handle
166 *
167 * This function removes a callback that was registered with
168 * qemu_add_wait_object.
169 *
170 * @func: The function that was passed to qemu_add_wait_object.
171 * @opaque: A pointer-size value that was passed to qemu_add_wait_object.
172 */
173 void qemu_del_wait_object(HANDLE handle, WaitObjectFunc *func, void *opaque);
174 #endif
175
176 /* async I/O support */
177
178 typedef void IOReadHandler(void *opaque, const uint8_t *buf, int size);
179 typedef int IOCanReadHandler(void *opaque);
180 typedef void IOHandler(void *opaque);
181
182 /**
183 * qemu_set_fd_handler2: Register a file descriptor with the main loop
184 *
185 * This function tells the main loop to wake up whenever one of the
186 * following conditions is true:
187 *
188 * 1) if @fd_write is not %NULL, when the file descriptor is writable;
189 *
190 * 2) if @fd_read is not %NULL, when the file descriptor is readable.
191 *
192 * @fd_read_poll can be used to disable the @fd_read callback temporarily.
193 * This is useful to avoid calling qemu_set_fd_handler2 every time the
194 * client becomes interested in reading (or dually, stops being interested).
195 * A typical example is when @fd is a listening socket and you want to bound
196 * the number of active clients. Remember to call qemu_notify_event whenever
197 * the condition may change from %false to %true.
198 *
199 * The callbacks that are set up by qemu_set_fd_handler2 are level-triggered.
200 * If @fd_read does not read from @fd, or @fd_write does not write to @fd
201 * until its buffers are full, they will be called again on the next
202 * iteration.
203 *
204 * @fd: The file descriptor to be observed. Under Windows it must be
205 * a #SOCKET.
206 *
207 * @fd_read_poll: A function that returns 1 if the @fd_read callback
208 * should be fired. If the function returns 0, the main loop will not
209 * end its iteration even if @fd becomes readable.
210 *
211 * @fd_read: A level-triggered callback that is fired if @fd is readable
212 * at the beginning of a main loop iteration, or if it becomes readable
213 * during one.
214 *
215 * @fd_write: A level-triggered callback that is fired when @fd is writable
216 * at the beginning of a main loop iteration, or if it becomes writable
217 * during one.
218 *
219 * @opaque: A pointer-sized value that is passed to @fd_read_poll,
220 * @fd_read and @fd_write.
221 */
222 int qemu_set_fd_handler2(int fd,
223 IOCanReadHandler *fd_read_poll,
224 IOHandler *fd_read,
225 IOHandler *fd_write,
226 void *opaque);
227
228 /**
229 * qemu_set_fd_handler: Register a file descriptor with the main loop
230 *
231 * This function tells the main loop to wake up whenever one of the
232 * following conditions is true:
233 *
234 * 1) if @fd_write is not %NULL, when the file descriptor is writable;
235 *
236 * 2) if @fd_read is not %NULL, when the file descriptor is readable.
237 *
238 * The callbacks that are set up by qemu_set_fd_handler are level-triggered.
239 * If @fd_read does not read from @fd, or @fd_write does not write to @fd
240 * until its buffers are full, they will be called again on the next
241 * iteration.
242 *
243 * @fd: The file descriptor to be observed. Under Windows it must be
244 * a #SOCKET.
245 *
246 * @fd_read: A level-triggered callback that is fired if @fd is readable
247 * at the beginning of a main loop iteration, or if it becomes readable
248 * during one.
249 *
250 * @fd_write: A level-triggered callback that is fired when @fd is writable
251 * at the beginning of a main loop iteration, or if it becomes writable
252 * during one.
253 *
254 * @opaque: A pointer-sized value that is passed to @fd_read and @fd_write.
255 */
256 int qemu_set_fd_handler(int fd,
257 IOHandler *fd_read,
258 IOHandler *fd_write,
259 void *opaque);
260
261 typedef struct QEMUBH QEMUBH;
262 typedef void QEMUBHFunc(void *opaque);
263
264 /**
265 * qemu_bh_new: Allocate a new bottom half structure.
266 *
267 * Bottom halves are lightweight callbacks whose invocation is guaranteed
268 * to be wait-free, thread-safe and signal-safe. The #QEMUBH structure
269 * is opaque and must be allocated prior to its use.
270 */
271 QEMUBH *qemu_bh_new(QEMUBHFunc *cb, void *opaque);
272
273 /**
274 * qemu_bh_schedule: Schedule a bottom half.
275 *
276 * Scheduling a bottom half interrupts the main loop and causes the
277 * execution of the callback that was passed to qemu_bh_new.
278 *
279 * Bottom halves that are scheduled from a bottom half handler are instantly
280 * invoked. This can create an infinite loop if a bottom half handler
281 * schedules itself.
282 *
283 * @bh: The bottom half to be scheduled.
284 */
285 void qemu_bh_schedule(QEMUBH *bh);
286
287 /**
288 * qemu_bh_cancel: Cancel execution of a bottom half.
289 *
290 * Canceling execution of a bottom half undoes the effect of calls to
291 * qemu_bh_schedule without freeing its resources yet. While cancellation
292 * itself is also wait-free and thread-safe, it can of course race with the
293 * loop that executes bottom halves unless you are holding the iothread
294 * mutex. This makes it mostly useless if you are not holding the mutex.
295 *
296 * @bh: The bottom half to be canceled.
297 */
298 void qemu_bh_cancel(QEMUBH *bh);
299
300 /**
301 *qemu_bh_delete: Cancel execution of a bottom half and free its resources.
302 *
303 * Deleting a bottom half frees the memory that was allocated for it by
304 * qemu_bh_new. It also implies canceling the bottom half if it was
305 * scheduled.
306 *
307 * @bh: The bottom half to be deleted.
308 */
309 void qemu_bh_delete(QEMUBH *bh);
310
311 #ifdef CONFIG_POSIX
312 /**
313 * qemu_add_child_watch: Register a child process for reaping.
314 *
315 * Under POSIX systems, a parent process must read the exit status of
316 * its child processes using waitpid, or the operating system will not
317 * free some of the resources attached to that process.
318 *
319 * This function directs the QEMU main loop to observe a child process
320 * and call waitpid as soon as it exits; the watch is then removed
321 * automatically. It is useful whenever QEMU forks a child process
322 * but will find out about its termination by other means such as a
323 * "broken pipe".
324 *
325 * @pid: The pid that QEMU should observe.
326 */
327 int qemu_add_child_watch(pid_t pid);
328 #endif
329
330 /**
331 * qemu_mutex_lock_iothread: Lock the main loop mutex.
332 *
333 * This function locks the main loop mutex. The mutex is taken by
334 * qemu_init_main_loop and always taken except while waiting on
335 * external events (such as with select). The mutex should be taken
336 * by threads other than the main loop thread when calling
337 * qemu_bh_new(), qemu_set_fd_handler() and basically all other
338 * functions documented in this file.
339 *
340 * NOTE: tools currently are single-threaded and qemu_mutex_lock_iothread
341 * is a no-op there.
342 */
343 void qemu_mutex_lock_iothread(void);
344
345 /**
346 * qemu_mutex_unlock_iothread: Unlock the main loop mutex.
347 *
348 * This function unlocks the main loop mutex. The mutex is taken by
349 * qemu_init_main_loop and always taken except while waiting on
350 * external events (such as with select). The mutex should be unlocked
351 * as soon as possible by threads other than the main loop thread,
352 * because it prevents the main loop from processing callbacks,
353 * including timers and bottom halves.
354 *
355 * NOTE: tools currently are single-threaded and qemu_mutex_unlock_iothread
356 * is a no-op there.
357 */
358 void qemu_mutex_unlock_iothread(void);
359
360 /* internal interfaces */
361
362 void qemu_iohandler_fill(int *pnfds, fd_set *readfds, fd_set *writefds, fd_set *xfds);
363 void qemu_iohandler_poll(fd_set *readfds, fd_set *writefds, fd_set *xfds, int rc);
364
365 void qemu_bh_schedule_idle(QEMUBH *bh);
366 int qemu_bh_poll(void);
367 void qemu_bh_update_timeout(int *timeout);
368
369 #endif