Commit 7a63f3cd authored by Stefan Hajnoczi's avatar Stefan Hajnoczi
Browse files

block: update bdrv_drain_all()/bdrv_drain() comments 



The doc comments for bdrv_drain_all() and bdrv_drain() are outdated:

 * The bdrv_drain() comment is a poor man's bdrv_lock()/bdrv_unlock()
   which Fam Zheng is currently developing.  Unfortunately this warning
   was never really enough because devices keep submitting I/O and op
   blockers don't prevent that.

 * The bdrv_drain_all() comment is still partially correct but reflects
   the nature of the implementation rather than API documentation.

Do make it clear that bdrv_drain() is only appropriate within an
AioContext.  For anything spanning AioContexts you need
bdrv_drain_all().

Cc: Markus Armbruster <armbru@redhat.com>
Cc: Paolo Bonzini <pbonzini@redhat.com>
Signed-off-by: default avatarStefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: default avatarMarkus Armbruster <armbru@redhat.com>
Reviewed-by: default avatarFam Zheng <famz@redhat.com>
Message-id: 1435854281-6078-1-git-send-email-stefanha@redhat.com
parent 1bd84ee7

block/io.c

+10 −10
Original line number Diff line number Diff line
@@ -236,12 +236,12 @@ static bool bdrv_requests_pending(BlockDriverState *bs) 
/*

 * Wait for pending requests to complete on a single BlockDriverState subtree

 *

 * See the warning in bdrv_drain_all().  This function can only be called if

 * you are sure nothing can generate I/O because you have op blockers

 * installed.

 *

 * Note that unlike bdrv_drain_all(), the caller must hold the BlockDriverState

 * AioContext.

 *

 * Only this BlockDriverState's AioContext is run, so in-flight requests must

 * not depend on events in other AioContexts.  In that case, use

 * bdrv_drain_all() instead.

 */

void bdrv_drain(BlockDriverState *bs)

{
@@ -260,12 +260,6 @@ void bdrv_drain(BlockDriverState *bs) 
 *

 * This function does not flush data to disk, use bdrv_flush_all() for that

 * after calling this function.

 *

 * Note that completion of an asynchronous I/O operation can trigger any

 * number of other I/O operations on other devices---for example a coroutine

 * can be arbitrarily complex and a constant flow of I/O can come until the

 * coroutine is complete.  Because of this, it is not possible to have a

 * function to drain a single device's I/O queue.

 */

void bdrv_drain_all(void)

{
@@ -288,6 +282,12 @@ void bdrv_drain_all(void) 
        }

    }



    /* Note that completion of an asynchronous I/O operation can trigger any

     * number of other I/O operations on other devices---for example a

     * coroutine can submit an I/O request to another device in response to

     * request completion.  Therefore we must keep looping until there was no

     * more activity rather than simply draining each device independently.

     */

    while (busy) {

        busy = false;