main-loop header

The documentation of QEMU’s qemu/main-loop.h header.

int qemu_init_main_loop(Error ** errp)

Parameters

Error ** errp

undescribed

Description

This includes setting up signal handlers. It should be called before any other threads are created. In addition, threads other than the main one should block signals that are trapped by the main loop. For simplicity, you can consider these signals to be safe: SIGUSR1, SIGUSR2, thread signals (SIGFPE, SIGILL, SIGSEGV, SIGBUS) and real-time signals if available. Remember that Windows in practice does not have signals, though.

In the case of QEMU tools, this will also start/initialize timers.

void main_loop_wait(int nonblocking)

Parameters

int nonblocking

Whether the caller should block until an event occurs.

Description

If nonblocking is true, poll for events, otherwise suspend until one actually occurs. The main loop usually consists of a loop that repeatedly calls main_loop_wait(false).

Main loop services include file descriptor callbacks, bottom halves and timers (defined in qemu-timer.h). Bottom halves are similar to timers that execute immediately, but have a lower overhead and scheduling them is wait-free, thread-safe and signal-safe.

It is sometimes useful to put a whole program in a coroutine. In this case, the coroutine actually should be started from within the main loop, so that the main loop can run whenever the coroutine yields. To do this, you can use a bottom half to enter the coroutine as soon as the main loop starts:

void enter_co_bh(void *opaque) {

QEMUCoroutine *co = opaque; qemu_coroutine_enter(co);

}

... QEMUCoroutine *co = qemu_coroutine_create(coroutine_entry, NULL); QEMUBH *start_bh = qemu_bh_new(enter_co_bh, co); qemu_bh_schedule(start_bh); while (...) {

main_loop_wait(false);

}

(In the future we may provide a wrapper for this).

AioContext * qemu_get_aio_context(void)

Parameters

void

no arguments

void qemu_notify_event(void)

Parameters

void

no arguments

Description

Similar to signaling a condition variable, qemu_notify_event forces main_loop_wait to look at pending events and exit. The caller of main_loop_wait will usually call it again very soon, so qemu_notify_event also has the side effect of recalculating the sets of file descriptors that the main loop waits for.

Calling qemu_notify_event is rarely necessary, because main loop services (bottom halves and timers) call it themselves.

int qemu_add_polling_cb(PollingFunc * func, void * opaque)

specific polling callback

Parameters

PollingFunc * func

The function that does the polling, and returns 1 to force immediate completion of main_loop_wait.

void * opaque

A pointer-size value that is passed to func.

Description

Currently, under Windows some events are polled rather than waited for. Polling callbacks do not ensure that func is called timely, because the main loop might wait for an arbitrarily long time. If possible, you should instead create a separate thread that does a blocking poll and set a Win32 event object. The event can then be passed to qemu_add_wait_object.

Polling callbacks really have nothing Windows specific in them, but as they are a hack and are currently not necessary under POSIX systems, they are only available when QEMU is running under Windows.

void qemu_del_polling_cb(PollingFunc * func, void * opaque)

specific polling callback

Parameters

PollingFunc * func

The function that was passed to qemu_add_polling_cb.

void * opaque

A pointer-size value that was passed to qemu_add_polling_cb.

Description

This function removes a callback that was registered with qemu_add_polling_cb.

int qemu_add_wait_object(HANDLE handle, WaitObjectFunc * func, void * opaque)

Parameters

HANDLE handle

The Windows handle to be observed.

WaitObjectFunc * func

A function to be called when handle is in a signaled state.

void * opaque

A pointer-size value that is passed to func.

Description

Under Windows, the iohandler mechanism can only be used with sockets. QEMU must use the WaitForMultipleObjects API to wait on other handles. This function registers a #HANDLE with QEMU, so that it will be included in the main loop’s calls to WaitForMultipleObjects. When the handle is in a signaled state, QEMU will call func.

void qemu_del_wait_object(HANDLE handle, WaitObjectFunc * func, void * opaque)

Parameters

HANDLE handle

undescribed

WaitObjectFunc * func

The function that was passed to qemu_add_wait_object.

void * opaque

A pointer-size value that was passed to qemu_add_wait_object.

Description

This function removes a callback that was registered with qemu_add_wait_object.

typedef int IOCanReadHandler(void * opaque)

Parameters

void * opaque

undescribed

Description

This function reports how many bytes #IOReadHandler is prepared to accept. #IOReadHandler may be invoked with up to this number of bytes. If this function returns 0 then #IOReadHandler is not invoked.

This function is typically called from an event loop. If the number of bytes changes outside the event loop (e.g. because a vcpu thread drained the buffer), then it is necessary to kick the event loop so that this function is called again. aio_notify() or qemu_notify_event() can be used to kick the event loop.

void qemu_set_fd_handler(int fd, IOHandler * fd_read, IOHandler * fd_write, void * opaque)

Parameters

int fd

The file descriptor to be observed. Under Windows it must be a #SOCKET.

IOHandler * fd_read

A level-triggered callback that is fired if fd is readable at the beginning of a main loop iteration, or if it becomes readable during one.

IOHandler * fd_write

A level-triggered callback that is fired when fd is writable at the beginning of a main loop iteration, or if it becomes writable during one.

void * opaque

A pointer-sized value that is passed to fd_read and fd_write.

Description

This function tells the main loop to wake up whenever one of the following conditions is true:

1. if fd_write is not NULL, when the file descriptor is writable;
2. if fd_read is not NULL, when the file descriptor is readable.

The callbacks that are set up by qemu_set_fd_handler are level-triggered. If fd_read does not read from fd, or fd_write does not write to fd until its buffers are full, they will be called again on the next iteration.

void event_notifier_set_handler(EventNotifier * e, EventNotifierHandler * handler)

Parameters

EventNotifier * e

The #EventNotifier to be observed.

EventNotifierHandler * handler

A level-triggered callback that is fired when e has been set. e is passed to it as a parameter.

Description

This function tells the main loop to wake up whenever the #EventNotifier was set.

int qemu_add_child_watch(pid_t pid)

Parameters

pid_t pid

The pid that QEMU should observe.

Description

Under POSIX systems, a parent process must read the exit status of its child processes using waitpid, or the operating system will not free some of the resources attached to that process.

This function directs the QEMU main loop to observe a child process and call waitpid as soon as it exits; the watch is then removed automatically. It is useful whenever QEMU forks a child process but will find out about its termination by other means such as a “broken pipe”.

bool qemu_mutex_iothread_locked(void)

Parameters

void

no arguments

Description

The main loop mutex is the coarsest lock in QEMU, and as such it must always be taken outside other locks. This function helps functions take different paths depending on whether the current thread is running within the main loop mutex.

qemu_mutex_lock_iothread()

Parameters

Description

This function locks the main loop mutex. The mutex is taken by main() in vl.c and always taken except while waiting on external events (such as with select). The mutex should be taken by threads other than the main loop thread when calling qemu_bh_new(), qemu_set_fd_handler() and basically all other functions documented in this file.

NOTE

tools currently are single-threaded and qemu_mutex_lock_iothread is a no-op there.

void qemu_mutex_unlock_iothread(void)

Parameters

void

no arguments

Description

This function unlocks the main loop mutex. The mutex is taken by main() in vl.c and always taken except while waiting on external events (such as with select). The mutex should be unlocked as soon as possible by threads other than the main loop thread, because it prevents the main loop from processing callbacks, including timers and bottom halves.

NOTE

tools currently are single-threaded and qemu_mutex_unlock_iothread is a no-op there.