Replace the obsolete iothread_get_aio_context() reference with the holder-aware API. Document matching get/put calls and their BQL requirements, and clarify that the unsafe accessor is for legacy callers only.
Signed-off-by: Zhang Chen <[email protected]> Reviewed-by: Stefan Hajnoczi <[email protected]> --- docs/devel/multiple-iothreads.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/devel/multiple-iothreads.rst b/docs/devel/multiple-iothreads.rst index a6eb046267..3bd8144ecc 100644 --- a/docs/devel/multiple-iothreads.rst +++ b/docs/devel/multiple-iothreads.rst @@ -88,11 +88,20 @@ argument, which is used to check for and prevent re-entrancy problems. For BHs associated with devices, the reentrancy-guard is contained in the corresponding ``DeviceState`` and named ``mem_reentrancy_guard``. -The ``AioContext`` can be obtained from the ``IOThread`` using -``iothread_get_aio_context()`` or for the main loop using -``qemu_get_aio_context()``. Code that takes an ``AioContext`` argument -works both in ``IOThread``\ s or the main loop, depending on which ``AioContext`` -instance the caller passes in. +The ``AioContext`` can be obtained from an ``IOThread`` using +``iothread_ref_and_get_aio_context(iothread, holder)``, or from the main loop +using ``qemu_get_aio_context()``. Code accepting an ``AioContext`` works with +either event loop. + +The ``iothread_ref_and_get_aio_context()`` registers a holder and takes +an IOThread reference. After the caller has finished using the context, +release the reference with ``iothread_unref_and_put_aio_context()``, passing +the same IOThread and an equivalent holder. Both calls require the BQL. +No matching IOThread put is needed for the main loop's context. + +``iothread_unsafe_get_aio_context()`` neither registers a holder nor takes a +reference. It is for legacy callers that ensure the IOThread's lifetime +themselves; new code must use the holder-aware API. How to synchronize with an ``IOThread`` --------------------------------------- -- 2.53.0
