doc: Mention proper use of handle

Although the proper use of the handle field during transmission
phase was implied, it never hurts to make it more explicit that
clients should alter the handle on each message, and the server
repeat the handle unchanged, in order for the client to track
when the server is sending replies out of order.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 doc/proto.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

On Mon, Mar 28, 2016 at 07:59:15AM -0600, Eric Blake wrote:
> Although the proper use of the handle field during transmission
> phase was implied, it never hurts to make it more explicit that
> clients should alter the handle on each message, and the server
> repeat the handle unchanged, in order for the client to track
> when the server is sending replies out of order.
> 
> Signed-off-by: Eric Blake <eblake@redhat.com>
> ---
>  doc/proto.md | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/proto.md b/doc/proto.md
> index 6d1cb34..d0102e0 100644
> --- a/doc/proto.md
> +++ b/doc/proto.md
> @@ -200,7 +200,11 @@ 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 send a
> +different value of handle for each request, and the server MUST use the
> +same value for handle as was sent by the client for each request that
> +the server is replying to, so that the client may correlate which
> +request is receiving a response.

NAK. This implies that a client should not ever reuse handles, while it
is legal for a client (and in fact the kernel does this) to reuse
handles once the server has ack'd the request.

On 03/29/2016 01:11 AM, Wouter Verhelst wrote:
> On Mon, Mar 28, 2016 at 07:59:15AM -0600, Eric Blake wrote:
>> Although the proper use of the handle field during transmission
>> phase was implied, it never hurts to make it more explicit that
>> clients should alter the handle on each message, and the server
>> repeat the handle unchanged, in order for the client to track
>> when the server is sending replies out of order.
>>

>>
>>  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 send a
>> +different value of handle for each request, and the server MUST use the
>> +same value for handle as was sent by the client for each request that
>> +the server is replying to, so that the client may correlate which
>> +request is receiving a response.
> 
> NAK. This implies that a client should not ever reuse handles, while it
> is legal for a client (and in fact the kernel does this) to reuse
> handles once the server has ack'd the request.

Nothing a little word-smithing can't fix.  I'll try a v2, probably along
the lines of:

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.

I wrote this in parallel with Alex's strawman proposals, so I
may have picked up on some of his ideas, while diverging in
other places.

Changes since v1: rebase, resend some pre-req patches, switch
from global/client flag negotiation over to option negotiation,
document a flags/type scheme in all structured replies, use
ONLY structured replies in response to a structured read, make
the server stream fully context-free (thanks to the type scheme),
go into more details about error reporting by using two different
structured errors (multiple errors each with offset, or single
error with no offset).

Eric Blake (2):
  doc: Mention proper use of handle
  doc: Propose Structured Read extension

Pavel Borzenkov (1):
  NBD proto: add "Command flags" section

 doc/proto.md | 282 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 277 insertions(+), 5 deletions(-)

Hi Eric,

On Tue, Mar 29, 2016 at 05:00:57PM -0600, Eric Blake wrote:
> I wrote this in parallel with Alex's strawman proposals, so I
> may have picked up on some of his ideas, while diverging in
> other places.
> 
> Changes since v1: rebase, resend some pre-req patches, switch
> from global/client flag negotiation over to option negotiation,
> document a flags/type scheme in all structured replies, use
> ONLY structured replies in response to a structured read, make
> the server stream fully context-free (thanks to the type scheme),
> go into more details about error reporting by using two different
> structured errors (multiple errors each with offset, or single
> error with no offset).
> 
> Eric Blake (2):
>   doc: Mention proper use of handle
>   doc: Propose Structured Read extension
> 
> Pavel Borzenkov (1):
>   NBD proto: add "Command flags" section

Thanks. 1 and 2 applied, 3 not yet (until resolution of discussion)

(not yet pushed yet, will do so later)