Re: [PATCH v2 1/3] docs: Prefer 'cookie' over 'handle'
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.
>
> 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.
I've gone ahead and pushed this series (after rebasing it on top of
your structured reply work, and enhancing the commit messages), I'll
ping the kernel list again about the uapi header change proposed
there.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
Reply to: