Re: [Libguestfs] [PATCH] docs: Prefer 'cookie' over 'handle'

In libnbd, we quickly learned that distinguishing between 'handle' (verb for acting on an object) and 'handle' (noun describing which object to act on) could get confusing; we solved it by renaming the latter to 'cookie'. Copy that approach into the NBD spec, and make it obvious that a cookie is opaque data from the point of view of the server. Makes no difference to implementations (other than older code still using 'handle' may be slightly harder to tie back to the spec). Suggested-by: Richard W.M. Jones <rjones(a)redhat.com&gt; Signed-off-by: Eric Blake <eblake(a)redhat.com&gt; --- doc/proto.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/proto.md b/doc/proto.md index 3a96703..abb23e8 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -301,11 +301,11 @@ may be handled by the server asynchronously), and structured reply chunks from one request may be interleaved with reply messages from other requests; however, there may be constraints that prevent arbitrary reordering of structured reply chunks within a given reply. -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 message +Clients SHOULD use a cookie that is distinct from all other currently +pending transactions, but MAY reuse cookies that are no longer in +flight; cookies need not be consecutive. In each reply message (whether simple or structured), the server MUST use the same value for -handle as was sent by the client in the corresponding request. In +cookie as was sent by the client in the corresponding request. In this way, the client can correlate which request is receiving a response. @@ -349,7 +349,7 @@ The request message, sent by the client, looks as follows: C: 32 bits, 0x25609513, magic (`NBD_REQUEST_MAGIC`) C: 16 bits, command flags C: 16 bits, type -C: 64 bits, handle +C: 64 bits, cookie C: 64 bits, offset (unsigned) C: 32 bits, length (unsigned) C: (*length* bytes of data if the request is of type `NBD_CMD_WRITE`) @@ -366,7 +366,7 @@ follows: S: 32 bits, 0x67446698, magic (`NBD_SIMPLE_REPLY_MAGIC`; used to be `NBD_REPLY_MAGIC`) S: 32 bits, error (MAY be zero) -S: 64 bits, handle +S: 64 bits, cookie S: (*length* bytes of data if the request is of type `NBD_CMD_READ` and *error* is zero) @@ -381,7 +381,7 @@ server must initiate a hard disconnect). Second, there is no way to efficiently skip over portions of a sparse file that are known to contain all zeroes. Finally, it is not possible to reliably decode the server traffic without also having context of what pending read -requests were sent by the client, to see which *handle* values will +requests were sent by the client, to see which *cookie* values will have accompanying payload on success. Therefore structured replies are also permitted if negotiated. @@ -398,7 +398,7 @@ sending errors via a structured reply, as the error can then be accompanied by a string payload to present to a human user. A structured reply MAY occupy multiple structured chunk messages -(all with the same value for "handle"), and the +(all with the same value for "cookie"), and the `NBD_REPLY_FLAG_DONE` reply flag is used to identify the final chunk. Unless further documented by individual requests below, the chunks MAY be sent in any order, except that the chunk with @@ -418,7 +418,7 @@ A structured reply chunk message looks as follows: S: 32 bits, 0x668e33ef, magic (`NBD_STRUCTURED_REPLY_MAGIC`) S: 16 bits, flags S: 16 bits, type -S: 64 bits, handle +S: 64 bits, cookie S: 32 bits, length of payload (unsigned) S: *length* bytes of payload data (if *length* is nonzero)