Re: [PATCH v2 2/2] manual/llio.texi: update manual to document file-private locks

[Jeff Layton <jlayton at redhat dot com>]

On Wed, 16 Apr 2014 12:00:58 -0400
Jeff Layton <jlayton@redhat.com> wrote:

> On Wed, 16 Apr 2014 17:37:53 +0200
> Michael Kerrisk <mtk.manpages@gmail.com> wrote:
> 
> > Jeff, (and Carlos)
> > 
> > > On Sat, 12 Apr 2014 12:52:33 -0400
> > > "Carlos O'Donell" <carlos@redhat.com> wrote:
> > 
> > [...]
> > 
> > 
> > >> OT: Why is it F_*LKP? What does the "P" part of "LKP" mean?
> > 
> > That does not strike me as OT at all. The existing byte-range locking
> > system has persisted (despite egregious faults) for well over two
> > decades. One supposes that Jeff's new improved version might be around
> > at least as long. With that in mind, and before setting in stone (and
> > pushing into POSIX) a model of thinking that thousands of programmers
> > will live with for a long time, it's worth thinking about names.
> > 
> > > Sorry, forgot to answer this:
> > >
> > > "P" is for "Private". What can I say...I suck at naming things, and no
> > > one else proposed anything better. It's not too late to change that if
> > > you can come up with a better moniker, but we'd need to move fast
> > > before v3.15 ships.
> > 
> > I agree on the "suck" bit ;-). Carlos nailed it when he referred to
> > traditional byte-range locks as being "process-associated". That is
> > the distinction between these two two locking APIs: one associates
> > locks with the process, the other associates them with a file handle.
> > The terminology should reflect that difference.
> > 
> > From that perspective, the word "private" here makes no sense at all.
> > What does "private" mean in this context? (By their very definition,
> > file locks are not private--they're something that is visible between
> > processes.) Some thought should be given to fixing that name, now, so
> > that we have better terminology for the coming decades ;-).
> > 
> > I would at the least suggest renaming these locks to something like:
> > 
> >     file-associated locks
> > 
> 
> That might be ok.
> 
> > or
> > 
> >    file-handle locks
> > 
> 
> I'd avoid this. "File handle" has certain connotations in context of
> NFS, and other (completely different) connotations in other situations.
> 
> > or (using POSIX terminology)
> > 
> >     file-description locks
> > 
> > but that last might be a bit confusing.
> > 
> 
> Again, somewhat confusing since they aren't tied to the file-descriptor
> per-se. Consider interactions with dup(), for instance.
> 
> > With some thought, you might also come up with an even better name.
> > But, I think *all* of the above alternatives are better than
> > "file-private locks".
> > 
> 
> Another possibility is file-owned locks. That's really
> closer to how the model works inside the kernel anyway. We have an
> opaque "owner" of the file (an unsigned long basically). Process
> associated locks use a pointer to the file descriptor table there.
> File-private locks (or whatever we want to call them) use a pointer to
> the "struct file".
> 
> > Please consider moving to one of those pieces of terminology, or a
> > better one of your own creation. Note that also implies that the names
> > of the constants should probably change. (Already, I found the
> > spelling of F_SETLKPW a little strange, since I expected F_SETLKWP.)
> > For example, if you went with the "file handle" terminology, then
> > something like:
> > 
> > F_FH_SETLK
> > F_FH_SETLKW
> > F_FH_GETLK
> > 
> > That also has the advantage of making the new constants more visually
> > distinctive in code. (I could easily see someone accidentally omitting
> > the "P" in F_SETLKP, and it would not be immediately obvious at a
> > casual scan.)
> > 
> 
> Where were these comments over the last several months? :)
> 
> It would have been better to do this before the v3.15 merge window. As
> it stands now, I think we can reasonably get the public facing
> interface changed as long as we do it in time for v3.15. I'd need to do
> some cleanup of the internal naming for v3.16 to make it all
> consistent, but that's doable.
> 
> Given my track record on naming things, I don't really trust myself to
> do this well, so you tell me...what's the ideal name and set of
> constants here?
> 


OTOH, as long as the numeric constants match up, it doesn't really
matter what the macros in the kernel are called. The only thing I think
we have to fix before v3.15 ships is the label in /proc/locks. We can't
reasonably change that after v3.15 ships.

FWIW, I'd probably prefer we rename these "file-associated locks" if
we're going to change the name. "file-owned" is probably closer to how
the internals work, but that'd probably confuse people with respect to
inode user/group owners.

That said, it's probably worth taking an extra day or two, and throwing
out a note to linux-fsdevel/linux-kernel to see if anyone else has
better names.

Thoughts?
-- 
Jeff Layton <jlayton@redhat.com>