Commit 40405851 authored by Jeff Moyer's avatar Jeff Moyer Committed by Jens Axboe
Browse files

block: clarify documentation for blk_{start|finish}_plug 



There was some confusion about what these functions did.  Make it clear
that this is a hint for upper layers to pass to the block layer, and
that it does not guarantee that I/O will not be submitted between a
start and finish plug.

Reported-by: default avatar"Darrick J. Wong" <darrick.wong@oracle.com>
Reviewed-by: default avatarDarrick J. Wong <darrick.wong@oracle.com>
Reviewed-by: default avatarMing Lei <ming.lei@redhat.com>
Signed-off-by: default avatarJeff Moyer <jmoyer@redhat.com>
Signed-off-by: default avatarJens Axboe <axboe@kernel.dk>
parent 373282e7

block/blk-core.c

+19 −0
Original line number Diff line number Diff line
@@ -1683,6 +1683,15 @@ EXPORT_SYMBOL(kblockd_mod_delayed_work_on); 
 * @plug:	The &struct blk_plug that needs to be initialized

 *

 * Description:

 *   blk_start_plug() indicates to the block layer an intent by the caller

 *   to submit multiple I/O requests in a batch.  The block layer may use

 *   this hint to defer submitting I/Os from the caller until blk_finish_plug()

 *   is called.  However, the block layer may choose to submit requests

 *   before a call to blk_finish_plug() if the number of queued I/Os

 *   exceeds %BLK_MAX_REQUEST_COUNT, or if the size of the I/O is larger than

 *   %BLK_PLUG_FLUSH_SIZE.  The queued I/Os may also be submitted early if

 *   the task schedules (see below).

 *

 *   Tracking blk_plug inside the task_struct will help with auto-flushing the

 *   pending I/O should the task end up blocking between blk_start_plug() and

 *   blk_finish_plug(). This is important from a performance perspective, but
@@ -1765,6 +1774,16 @@ void blk_flush_plug_list(struct blk_plug *plug, bool from_schedule) 
		blk_mq_flush_plug_list(plug, from_schedule);

}



/**

 * blk_finish_plug - mark the end of a batch of submitted I/O

 * @plug:	The &struct blk_plug passed to blk_start_plug()

 *

 * Description:

 * Indicate that a batch of I/O submissions is complete.  This function

 * must be paired with an initial call to blk_start_plug().  The intent

 * is to allow the block layer to optimize I/O submission.  See the

 * documentation for blk_start_plug() for more information.

 */

void blk_finish_plug(struct blk_plug *plug)

{

	if (plug != current->plug)

CRA Git | Maintained and supported by SUSTech CRA and CCSE