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

--- 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 +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. + +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 -- 2.21.0