docs/devel/multiple-iothreads.rst

5    Copyright (c) 2014-2017 Red Hat Inc.
8    the COPYING file in the top-level directory.
11 This document explains the ``IOThread`` feature and how to write code that runs
15 ---------------------------------
16 QEMU is an event-driven program that can do several things at once using an
21 The default event loop is called the main loop (see ``main-loop.c``).  It is
23 ``-object iothread,id=my-iothread``.
30 ------------------------------
32 scalability bottleneck on hosts with many CPUs.  Work can be spread across
39 QEMU's code historically was not thread-safe.
45 The experimental ``virtio-blk`` data-plane implementation has been benchmarked and
49 .. _how-to-program:
52 ----------------------------------
60  * File descriptor monitoring (read/write/error on POSIX hosts)
61  * Event notifiers (inter-thread signalling)
66  * LEGACY ``qemu_aio_set_fd_handler()`` - monitor a file descriptor
67  * LEGACY ``qemu_aio_set_event_notifier()`` - monitor an event notifier
68  * LEGACY ``timer_new_ms()`` - create a timer
69  * LEGACY ``qemu_bh_new()`` - create a BH
70  * LEGACY ``qemu_bh_new_guarded()`` - create a BH with a device re-entrancy guard
71  * LEGACY ``qemu_aio_wait()`` - run an event loop iteration
73 Since they implicitly work on the main loop they cannot be used in code that
74 runs in an ``IOThread``.  They might cause a crash or deadlock if called from an
78  * ``aio_set_fd_handler()`` - monitor a file descriptor
79  * ``aio_set_event_notifier()`` - monitor an event notifier
80  * ``aio_timer_new()`` - create a timer
81  * ``aio_bh_new()`` - create a BH
82  * ``aio_bh_new_guarded()`` - create a BH with a device re-entrancy guard
83  * ``aio_poll()`` - run an event loop iteration
87 argument, which is used to check for and prevent re-entrancy problems. For
88 BHs associated with devices, the reentrancy-guard is contained in the
94 works both in ``IOThread``\ s or the main loop, depending on which ``AioContext``
98 ---------------------------------------
104 are thread-safe. They can be used to trigger activity in an ``IOThread``.
113 ----------------------------------
125 `How to program for IOThreads`_ for information on how to do that.
134 Long-running jobs (usually in the form of coroutines) are often scheduled in