On Sat, Mar 4, 2023 at 12:15?AM Eric Blake <eblake at redhat.com> wrote:> > 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.Good change, will make it easier to search code. But the actual text does not make it clear that a cookie is opaque data from point of view of the client. Maybe make this more clear?> Makes no difference to implementations (other than older code > still using 'handle' may be slightly harder to tie back to the spec).To avoid confusion with older code that carefully used "handle" to match the spec, maybe add a note that "cookie" was named "handle" before? Nir
Wouter Verhelst
2023-Mar-05 08:53 UTC
[Libguestfs] [PATCH] docs: Prefer 'cookie' over 'handle'
On Sat, Mar 04, 2023 at 10:03:46PM +0200, Nir Soffer wrote:> On Sat, Mar 4, 2023 at 12:15?AM Eric Blake <eblake at redhat.com> wrote: > > Makes no difference to implementations (other than older code > > still using 'handle' may be slightly harder to tie back to the spec). > > To avoid confusion with older code that carefully used "handle" to match > the spec, maybe add a note that "cookie" was named "handle" before?Yes, this. I'm happy with renaming it cookie (it makes sense), but there is a *lot* of stuff out there that calls it "handle" (including a wireshark plugin) and it would be confusing if that link isn't available anywhere. -- w at uter.{be,co.za} wouter@{grep.be,fosdem.org,debian.org} I will have a Tin-Actinium-Potassium mixture, thanks.
Seemingly Similar Threads
- [PATCH v2 1/6] spec: Recommend cap on NBD_REPLY_TYPE_BLOCK_STATUS length
- [PATCH v2 3/6] spec: Add NBD_OPT_EXTENDED_HEADERS
- [PATCH v2 2/6] spec: Tweak description of maximum block size
- [PATCH] docs: Prefer 'cookie' over 'handle'
- [PATCH v2 5/6] spec: Introduce NBD_FLAG_BLOCK_STATUS_PAYLOAD