Re: [PATCH v2 1/3] docs: Prefer 'cookie' over 'handle'

[Wouter Verhelst <w@uter.be>]

So.

On Thu, Mar 09, 2023 at 03:06:21PM -0600, Eric Blake 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.  Makes no difference to implementations (other than older code
> still using 'handle' may be slightly harder to tie back to the spec).

One thing I didn't think about:

The kernel has a uapi include file that mentions "handle". That's where
the name comes from, in fact: the nbd.h in the nbd project was
originally not even there, we just required you either compile on Linux
or copy the file somehow. It was so much of a bother that I eventually
gave up on that and copied a (by now somewhat outdated and independently
evolved) version of nbd.h into the nbd repository.

I'm still happy to make these changes, but we should consider what to do
with the kernel and the uapi include file. Renaming it there is probably
not going to happen; we might do some union or macro trickery to create
an alias to "cookie" for the "handle" name, but I don't know what the
kernel community is going to think about that.

Alternatively, perhaps we may have to tweak the wording a bit more to
clarify that it's not just older code.

-- 
     w@uter.{be,co.za}
wouter@{grep.be,fosdem.org,debian.org}

I will have a Tin-Actinium-Potassium mixture, thanks.