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

[Eric Blake <eblake@redhat.com>]

On Fri, Mar 10, 2023 at 11:48:46AM +0200, Wouter Verhelst wrote:
> 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.

Huh, I've never even tried to use that file.  I'll try my hand at
patching it to use an anonymous union allowing 'char handle[8]' and
'__be64 cookie' to coincide (doesn't change compilation of the kernel
code using handle, but lets user-space use cookie) - we'll see where
that goes (I do not have a track record of kernel commits to date).
Depending on what happens there, I'm happy to tweak this patch in
turn.

> 
> 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.

I can wait a couple days for response from the kernel side.

> 
> 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.
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org