[Libguestfs] [PATCH libnbd discussion only 2/5] docs: Document multiple in-flight requests.

[Eric Blake]

On 6/3/19 10:29 AM, Richard W.M. Jones wrote:
> ---
>  docs/libnbd.pod | 29 ++++++++++++++++++++++++++++-
>  1 file changed, 28 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/libnbd.pod b/docs/libnbd.pod
> index f299ef1..7cbb9cd 100644
> --- a/docs/libnbd.pod
> +++ b/docs/libnbd.pod
> @@ -334,7 +334,30 @@ to prefetch.
>  
>  =back
>  
> -=head1 MULTI-CONN
> +=head1 PERFORMANCE
> +
> +=head2 Issuing multiple in-flight requests
> +
> +NBD servers which properly implement the spec can handle multiple

Should we spell this out as 'specification' rather than abbreviating to
'spec'?

> +requests in flight over the same connection at the same time.  Libnbd
> +supports this when using the low level API.  To use it you simply
> +issue more requests as needed (eg. using calls like C<nbd_aio_pread>,
> +C<nbd_aio_pwrite>) without waiting for previous commands to complete.
> +
> +Each request is identified by a unique 64 bit handle (assigned by
> +libnbd), allowing libnbd and callers to match replies to requests.
> +Replies may arrive out of order.
> +
> +Although in theory you can have an indefinite number of requests in
> +flight at the same time, in practice it's a good idea to limit them to
> +some number.  It is suggested to start with a limit of 16 requests in
> +flight (per NBD connection), and measure how adjusting the limit up
> +and down affects performance for your local configuration.

Probably also worth advising that parallel in-flight requests should
avoid any request that overlaps a portion of the disk that is already
the subject of any other in-flight write-like command (a parallel read
may see indeterminate data, and a parallel write may even cause disk
corruption where the resulting disk contents do not match either of the
two writes).

> +
> +There is a full example using multiple in-flight requests available at
> +L<https://github.com/libguestfs/libnbd/blob/master/examples/threaded-reads-and-writes.c>
> +
> +=head2 Multi-conn
>  
>  Some NBD servers advertise “multi-conn” which means that it is safe to
>  make multiple connections to the server and load-balance commands
> @@ -358,6 +381,10 @@ If multi-conn is supported then you can open further connections:
>     nbd[i]_connect_tcp (nbd[i], "server", "10809");
>   }
>  
> +If you are issuing multiple in-flight requests (see above) and
> +limiting the number, then the limit should be applied to each
> +individual NBD connection.
> +
>  =head1 ENCRYPTION AND AUTHENTICATION
>  
>  The NBD protocol and libnbd supports TLS (sometimes incorrectly called
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libguestfs/attachments/20190603/4e25f9cf/attachment.sig>