[v2,2/3] doc: Mention proper use of handle

Commit Message

Eric Blake March 29, 2016, 11 p.m. UTC

Although the proper use of the handle field during transmission
phase was implied, it never hurts to make it more explicit that
clients should use distinct handles for multiple in-flight requests.
Likewise, the server must repeat the handle unchanged, in order for
the client to track when the server is sending replies out of order.
Make it clear that the client does not have to follow any particular
order of handles, and can reuse values.

Signed-off-by: Eric Blake <[e-mail]>
---
 doc/proto.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

Patch

diff --git a/doc/proto.md b/doc/proto.md
index 3d49162..3f9ee23 100644
--- a/doc/proto.md
+++ b/doc/proto.md
@@ -203,7 +203,13 @@  S: 64 bits, handle
 S: (*length* bytes of data if the request is of type `NBD_CMD_READ`)

 Replies need not be sent in the same order as requests (i.e., requests
-may be handled by the server asynchronously).
+may be handled by the server asynchronously).  Clients SHOULD use a
+handle that is distinct from all other currently pending transactions,
+but MAY reuse handles that are no longer in flight; handles need not
+be consecutive.  In each reply, the server MUST use the same value for
+handle as was sent by the client in the corresponding request.  In
+this way, the client can correlate which request is receiving a
+response.

 ## Values