[PATCH v2 0/1] Update doc for option rw_sequencer

[PATCH v2 0/1] Update doc for option rw_sequencer

[Ankit Kumar]

Fixes: https://github.com/axboe/fio/issues/1223

Changes since v1:
 - Changed the wording for rw_sequencer=sequential as per
   Vincent's feedback.
 - Added few examples explaining about rw_sequencer.

Ankit Kumar (1):
  doc: clarify the usage of rw_sequencer

 HOWTO.rst | 35 ++++++++++++++++++++++++++++-------
 fio.1     | 47 +++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 69 insertions(+), 13 deletions(-)

-- 
2.17.1

[PATCH v2 1/1] doc: clarify the usage of rw_sequencer

[Ankit Kumar]

Update man page clarifying the usage of rw_sequencer=sequential
Added few examples explaining the offset generation for rw_sequencer.

Fixes: https://github.com/axboe/fio/issues/1223

Signed-off-by: Ankit Kumar <ankit.kumar@samsung.com>
---
 HOWTO.rst | 35 ++++++++++++++++++++++++++++-------
 fio.1     | 47 +++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 69 insertions(+), 13 deletions(-)

diff --git a/HOWTO.rst b/HOWTO.rst
index 0a48a453..17caaf5d 100644
--- a/HOWTO.rst
+++ b/HOWTO.rst
@@ -1176,13 +1176,34 @@ I/O type
 			Generate the same offset.
 
 	``sequential`` is only useful for random I/O, where fio would normally
-	generate a new random offset for every I/O. If you append e.g. 8 to randread,
-	you would get a new random offset for every 8 I/Os. The result would be a
-	seek for only every 8 I/Os, instead of for every I/O. Use ``rw=randread:8``
-	to specify that. As sequential I/O is already sequential, setting
-	``sequential`` for that would not result in any differences.  ``identical``
-	behaves in a similar fashion, except it sends the same offset 8 number of
-	times before generating a new offset.
+	generate a new random offset for every I/O. If you append e.g. 8 to
+	randread, i.e. ``rw=randread:8`` you would get a new random offset for
+	every 8 I/Os. The result would be a sequence of 8 sequential offsets
+	with a random starting point. However this behavior may change if a
+	sequential I/O reaches end of the file. As sequential I/O is already
+	sequential, setting ``sequential`` for that would not result in any
+	difference. ``identical`` behaves in a similar fashion, except it sends
+	the same offset 8 number of times before generating a new offset.
+
+	Example #1::
+
+		rw=randread:8
+		rw_sequencer=sequential
+		bs=4k
+
+	The generated sequence of offsets will look like this:
+	4k, 8k, 12k, 16k, 20k, 24k, 28k, 32k, 92k, 96k, 100k, 104k, 108k,
+	112k, 116k, 120k, 48k, 52k ...
+
+	Example #2::
+
+		rw=randread:8
+		rw_sequencer=identical
+		bs=4k
+
+	The generated sequence of offsets will look like this:
+	4k, 4k, 4k, 4k, 4k, 4k, 4k, 4k, 92k, 92k, 92k, 92k, 92k, 92k, 92k, 92k,
+	48k, 48k, 48k ...
 
 .. option:: unified_rw_reporting=str
 
diff --git a/fio.1 b/fio.1
index eb87533f..527b3d46 100644
--- a/fio.1
+++ b/fio.1
@@ -952,12 +952,47 @@ Generate the same offset.
 .P
 \fBsequential\fR is only useful for random I/O, where fio would normally
 generate a new random offset for every I/O. If you append e.g. 8 to randread,
-you would get a new random offset for every 8 I/Os. The result would be a
-seek for only every 8 I/Os, instead of for every I/O. Use `rw=randread:8'
-to specify that. As sequential I/O is already sequential, setting
-\fBsequential\fR for that would not result in any differences. \fBidentical\fR
-behaves in a similar fashion, except it sends the same offset 8 number of
-times before generating a new offset.
+i.e. `rw=randread:8' you would get a new random offset for every 8 I/Os. The
+result would be a sequence of 8 sequential offsets with a random starting
+point.  However this behavior may change if a sequential I/O reaches end of the
+file. As sequential I/O is already sequential, setting \fBsequential\fR for
+that would not result in any difference. \fBidentical\fR behaves in a similar
+fashion, except it sends the same offset 8 number of times before generating a
+new offset.
+.P
+.P
+Example #1:
+.RS
+.P
+.PD 0
+rw=randread:8
+.P
+rw_sequencer=sequential
+.P
+bs=4k
+.PD
+.RE
+.P
+The generated sequence of offsets will look like this:
+4k, 8k, 12k, 16k, 20k, 24k, 28k, 32k, 92k, 96k, 100k, 104k, 108k, 112k, 116k,
+120k, 48k, 52k ...
+.P
+.P
+Example #2:
+.RS
+.P
+.PD 0
+rw=randread:8
+.P
+rw_sequencer=identical
+.P
+bs=4k
+.PD
+.RE
+.P
+The generated sequence of offsets will look like this:
+4k, 4k, 4k, 4k, 4k, 4k, 4k, 4k, 92k, 92k, 92k, 92k, 92k, 92k, 92k, 92k, 48k,
+48k, 48k ...
 .RE
 .TP
 .BI unified_rw_reporting \fR=\fPstr
-- 
2.17.1

Re: [PATCH v2 0/1] Update doc for option rw_sequencer

[Vincent Fu]

On 1/11/23 01:48, Ankit Kumar wrote:
> Fixes: https://github.com/axboe/fio/issues/1223
> 
> Changes since v1:
>   - Changed the wording for rw_sequencer=sequential as per
>     Vincent's feedback.
>   - Added few examples explaining about rw_sequencer.
> 
> Ankit Kumar (1):
>    doc: clarify the usage of rw_sequencer
> 
>   HOWTO.rst | 35 ++++++++++++++++++++++++++++-------
>   fio.1     | 47 +++++++++++++++++++++++++++++++++++++++++------
>   2 files changed, 69 insertions(+), 13 deletions(-)
> 

Applied. Thanks.