should we change the name/macros of file-private locks?

should we change the name/macros of file-private locks?

[Jeff Layton]

Sorry to spam so many lists, but I think this needs widespread
distribution and consensus.

File-private locks have been merged into Linux for v3.15, and *now*
people are commenting that the name and macro definitions for the new
file-private locks suck.

...and I can't even disagree. They do suck.

We're going to have to live with these for a long time, so it's
important that we be happy with the names before we're stuck with them.

Michael Kerrisk suggested several names but I think the only one that
doesn't have other issues is "file-associated locks", which can be
distinguished against "process-associated" locks (aka classic POSIX
locks).

At the same time, he suggested that we rename the command macros since
the 'P' suffix would no longer be relevant. He suggested something like
this:

    F_FA_GETLK
    F_FA_SETLK
    F_FA_SETLKW

That would also make them more visually distinguishable from the
classic F_GETLK/F_SETLK/F_SETLKW commands. I like that change in
particular, as the original macros names would be easy to typo.

I think we'd also need to rename how these are reported in /proc/locks.
Currently they have a type label of "FLPVT". I'd suggest that we
change that to "FASSOC". For v3.15, this is the only part we'd
absolutely have to change before it ships. The rest I can fix up in
v3.16.

Does this sound like a reasonable set of changes to make? Does anyone
else have a better set of names they can suggest? Speak now, or forever
hold your peace!

-- 
Jeff Layton <jlayton@redhat.com>

Re: should we change the name/macros of file-private locks?

[Michael Kerrisk (man-pages)]

[CC += Jeremy Allison]

On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
> Sorry to spam so many lists, but I think this needs widespread
> distribution and consensus.
>
> File-private locks have been merged into Linux for v3.15, and *now*
> people are commenting that the name and macro definitions for the new
> file-private locks suck.
>
> ...and I can't even disagree. They do suck.
>
> We're going to have to live with these for a long time, so it's
> important that we be happy with the names before we're stuck with them.

So, to add my perspective: 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.

> Michael Kerrisk suggested several names but I think the only one that
> doesn't have other issues is "file-associated locks", which can be
> distinguished against "process-associated" locks (aka classic POSIX
> locks).

The names I have suggested are:

    file-associated locks

or

   file-handle locks

or (using POSIX terminology)

    file-description locks

but that last might be a bit confusing to people who are not
standards-aware. (The POSIX standard defines the thing that a "file
descriptor" refers to as a "file description"; other people often call
that thing a "file handle" or an "open file table entry" or a "struct
file". The POSIX term is precise and unambiguous, but, unfortunately,
the term is not common outside the standard and is also easily
mistaken for "file descriptor".)

> At the same time, he suggested that we rename the command macros since
> the 'P' suffix would no longer be relevant. He suggested something like
> this:
>
>     F_FA_GETLK
>     F_FA_SETLK
>     F_FA_SETLKW
>
> That would also make them more visually distinguishable from the
> classic F_GETLK/F_SETLK/F_SETLKW commands. I like that change in
> particular, as the original macros names would be easy to typo.
>
> I think we'd also need to rename how these are reported in /proc/locks.
> Currently they have a type label of "FLPVT". I'd suggest that we
> change that to "FASSOC". For v3.15, this is the only part we'd
> absolutely have to change before it ships. The rest I can fix up in
> v3.16.
>
> Does this sound like a reasonable set of changes to make? Does anyone
> else have a better set of names they can suggest? Speak now, or forever
> hold your peace!

I think none of my suggested terms is perfect, but they at least have
the virtue of being better than "file-private lock", since the term
"private" is somewhat nonsensical. It may be that someone else has an
even better idea for a term for these new kinds of locks.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: should we change the name/macros of file-private locks?

[Jeremy Allison]

On Wed, Apr 16, 2014 at 10:00:46PM +0200, Michael Kerrisk (man-pages) wrote:
> [CC += Jeremy Allison]
> 
> On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
> > Sorry to spam so many lists, but I think this needs widespread
> > distribution and consensus.
> >
> > File-private locks have been merged into Linux for v3.15, and *now*
> > people are commenting that the name and macro definitions for the new
> > file-private locks suck.
> >
> > ...and I can't even disagree. They do suck.
> >
> > We're going to have to live with these for a long time, so it's
> > important that we be happy with the names before we're stuck with them.
> 
> So, to add my perspective: 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.
> 
> > Michael Kerrisk suggested several names but I think the only one that
> > doesn't have other issues is "file-associated locks", which can be
> > distinguished against "process-associated" locks (aka classic POSIX
> > locks).
> 
> The names I have suggested are:
> 
>     file-associated locks
> 
> or
> 
>    file-handle locks
> 
> or (using POSIX terminology)
> 
>     file-description locks

Thanks for the CC: Michael, but to be honest
I don't really care what the name is, I just
want the functionality. I can change our build
system to cope with detecting it under any name
you guys choose :-).

Cheers,

	Jeremy.

Re: should we change the name/macros of file-private locks?

[Stefan (metze) Metzmacher]

Am 16.04.2014 22:00, schrieb Michael Kerrisk (man-pages):
> [CC += Jeremy Allison]
> 
> On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
>> Sorry to spam so many lists, but I think this needs widespread
>> distribution and consensus.
>>
>> File-private locks have been merged into Linux for v3.15, and *now*
>> people are commenting that the name and macro definitions for the new
>> file-private locks suck.
>>
>> ...and I can't even disagree. They do suck.
>>
>> We're going to have to live with these for a long time, so it's
>> important that we be happy with the names before we're stuck with them.
> 
> So, to add my perspective: 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.
> 
>> Michael Kerrisk suggested several names but I think the only one that
>> doesn't have other issues is "file-associated locks", which can be
>> distinguished against "process-associated" locks (aka classic POSIX
>> locks).
> 
> The names I have suggested are:
> 
>     file-associated locks
> 
> or
> 
>    file-handle locks
> 
> or (using POSIX terminology)
> 
>     file-description locks

I'd use file-handle, file-description or at least something that's
not associated to the "file" itself.

file-handle-associated or file-description-associated would also work.

> but that last might be a bit confusing to people who are not
> standards-aware. (The POSIX standard defines the thing that a "file
> descriptor" refers to as a "file description"; other people often call
> that thing a "file handle" or an "open file table entry" or a "struct
> file". The POSIX term is precise and unambiguous, but, unfortunately,
> the term is not common outside the standard and is also easily
> mistaken for "file descriptor".)
> 
>> At the same time, he suggested that we rename the command macros since
>> the 'P' suffix would no longer be relevant. He suggested something like
>> this:
>>
>>     F_FA_GETLK
>>     F_FA_SETLK
>>     F_FA_SETLKW

With file-description-associated this could be

F_FDA_*

metze

Re: Re: [Nfs-ganesha-devel] should we change the name/macros of file-private locks?

[Jim Lieb]

On Wednesday, April 16, 2014 13:16:33 Jeremy Allison wrote:
> On Wed, Apr 16, 2014 at 10:00:46PM +0200, Michael Kerrisk (man-pages) wrote:
> > [CC += Jeremy Allison]
> > 
> > On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
> > > Sorry to spam so many lists, but I think this needs widespread
> > > distribution and consensus.
> > > 
> > > File-private locks have been merged into Linux for v3.15, and *now*
> > > people are commenting that the name and macro definitions for the new
> > > file-private locks suck.
> > > 
> > > ...and I can't even disagree. They do suck.
> > > 
> > > We're going to have to live with these for a long time, so it's
> > > important that we be happy with the names before we're stuck with them.
> > 
> > So, to add my perspective: 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.
> > 
> > > Michael Kerrisk suggested several names but I think the only one that
> > > doesn't have other issues is "file-associated locks", which can be
> > > distinguished against "process-associated" locks (aka classic POSIX
> > > locks).
> > 
> > The names I have suggested are:
> >     file-associated locks
> > 
> > or
> > 
> >    file-handle locks
> > 
> > or (using POSIX terminology)
> > 
> >     file-description locks
> 
> Thanks for the CC: Michael, but to be honest
> I don't really care what the name is, I just
> want the functionality. I can change our build
> system to cope with detecting it under any name
> you guys choose :-).
> 
> Cheers,
> 
> 	Jeremy.

I and the rest of the nfs-ganesha community are with Jeremy and samba wrt 
names.  We just want locks that work, i.e. Useful Locks ;)

Jim
> 
> ----------------------------------------------------------------------------
> -- Learn Graph Databases - Download FREE O'Reilly Book
> "Graph Databases" is the definitive new guide to graph databases and their
> applications. Written by three acclaimed leaders in the field,
> this first edition is now available. Download your free book today!
> http://p.sf.net/sfu/NeoTech
> _______________________________________________
> Nfs-ganesha-devel mailing list
> Nfs-ganesha-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/nfs-ganesha-devel

-- 
Jim Lieb
Linux Systems Engineer
Panasas Inc.

"If ease of use was the only requirement, we would all be riding tricycles"
- Douglas Engelbart 1925–2013

Re: [Nfs-ganesha-devel] should we change the name/macros of file-private locks?

[Michael Kerrisk (man-pages)]

On 04/17/2014 02:31 AM, Jim Lieb wrote:
> On Wednesday, April 16, 2014 13:16:33 Jeremy Allison wrote:
>> On Wed, Apr 16, 2014 at 10:00:46PM +0200, Michael Kerrisk (man-pages) wrote:
>>> [CC += Jeremy Allison]
>>>
>>> On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
>>>> Sorry to spam so many lists, but I think this needs widespread
>>>> distribution and consensus.
>>>>
>>>> File-private locks have been merged into Linux for v3.15, and *now*
>>>> people are commenting that the name and macro definitions for the new
>>>> file-private locks suck.
>>>>
>>>> ...and I can't even disagree. They do suck.
>>>>
>>>> We're going to have to live with these for a long time, so it's
>>>> important that we be happy with the names before we're stuck with them.
>>>
>>> So, to add my perspective: 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.
>>>
>>>> Michael Kerrisk suggested several names but I think the only one that
>>>> doesn't have other issues is "file-associated locks", which can be
>>>> distinguished against "process-associated" locks (aka classic POSIX
>>>> locks).
>>>
>>> The names I have suggested are:
>>>     file-associated locks
>>>
>>> or
>>>
>>>    file-handle locks
>>>
>>> or (using POSIX terminology)
>>>
>>>     file-description locks
>>
>> Thanks for the CC: Michael, but to be honest
>> I don't really care what the name is, I just
>> want the functionality. I can change our build
>> system to cope with detecting it under any name
>> you guys choose :-).
>>
>> Cheers,
>>
>> 	Jeremy.
> 
> I and the rest of the nfs-ganesha community are with Jeremy and samba wrt 
> names.  We just want locks that work, i.e. Useful Locks ;)

Yes, sure. The functionality is coming in any case, thanks to Jeff.
The point is: let's make the API as sane as we can. And that's what
this thread is about, so if you have insights or opinions on good 
naming, that would be helpful.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: should we change the name/macros of file-private locks?

[Jeff Layton]

On Thu, 17 Apr 2014 00:42:13 +0200
"Stefan (metze) Metzmacher" <metze@samba.org> wrote:

> Am 16.04.2014 22:00, schrieb Michael Kerrisk (man-pages):
> > [CC += Jeremy Allison]
> > 
> > On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
> >> Sorry to spam so many lists, but I think this needs widespread
> >> distribution and consensus.
> >>
> >> File-private locks have been merged into Linux for v3.15, and *now*
> >> people are commenting that the name and macro definitions for the new
> >> file-private locks suck.
> >>
> >> ...and I can't even disagree. They do suck.
> >>
> >> We're going to have to live with these for a long time, so it's
> >> important that we be happy with the names before we're stuck with them.
> > 
> > So, to add my perspective: 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.
> > 
> >> Michael Kerrisk suggested several names but I think the only one that
> >> doesn't have other issues is "file-associated locks", which can be
> >> distinguished against "process-associated" locks (aka classic POSIX
> >> locks).
> > 
> > The names I have suggested are:
> > 
> >     file-associated locks
> > 
> > or
> > 
> >    file-handle locks
> > 
> > or (using POSIX terminology)
> > 
> >     file-description locks
> 
> I'd use file-handle, file-description or at least something that's
> not associated to the "file" itself.
> 
> file-handle-associated or file-description-associated would also work.
> 

Yeah, I understand your point.

I'm not keen on using "file-handle" as file handles have a completely
different meaning in the context of something like NFS.

"file-description-associated" is rather a mouthful. You Germans might
go for that sort of thing, but it feels awkward to us knuckle-draggers
that primarily speak English.

Maybe we should just go with one of Michael's earlier suggestions --
"file-description locks" and change the macros to F_FD_*.

In the docs we could take pains to point out that these are
file-_description_ locks and not file-_descriptor_ locks, and outline
why that is so (which is something I'm trying to make crystal clear in
the docs anyway).

Does anyone object to that?

> > but that last might be a bit confusing to people who are not
> > standards-aware. (The POSIX standard defines the thing that a "file
> > descriptor" refers to as a "file description"; other people often call
> > that thing a "file handle" or an "open file table entry" or a "struct
> > file". The POSIX term is precise and unambiguous, but, unfortunately,
> > the term is not common outside the standard and is also easily
> > mistaken for "file descriptor".)
> > 
> >> At the same time, he suggested that we rename the command macros since
> >> the 'P' suffix would no longer be relevant. He suggested something like
> >> this:
> >>
> >>     F_FA_GETLK
> >>     F_FA_SETLK
> >>     F_FA_SETLKW
> 
> With file-description-associated this could be
> 
> F_FDA_*
> 
> metze


-- 
Jeff Layton <jlayton@redhat.com>

Re: should we change the name/macros of file-private locks?

[Michael Kerrisk (man-pages)]

On 04/17/2014 01:52 PM, Jeff Layton wrote:
> On Thu, 17 Apr 2014 00:42:13 +0200
> "Stefan (metze) Metzmacher" <metze@samba.org> wrote:
> 
>> Am 16.04.2014 22:00, schrieb Michael Kerrisk (man-pages):
>>> [CC += Jeremy Allison]
>>>
>>> On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
>>>> Sorry to spam so many lists, but I think this needs widespread
>>>> distribution and consensus.
>>>>
>>>> File-private locks have been merged into Linux for v3.15, and *now*
>>>> people are commenting that the name and macro definitions for the new
>>>> file-private locks suck.
>>>>
>>>> ...and I can't even disagree. They do suck.
>>>>
>>>> We're going to have to live with these for a long time, so it's
>>>> important that we be happy with the names before we're stuck with them.
>>>
>>> So, to add my perspective: 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.
>>>
>>>> Michael Kerrisk suggested several names but I think the only one that
>>>> doesn't have other issues is "file-associated locks", which can be
>>>> distinguished against "process-associated" locks (aka classic POSIX
>>>> locks).
>>>
>>> The names I have suggested are:
>>>
>>>     file-associated locks
>>>
>>> or
>>>
>>>    file-handle locks
>>>
>>> or (using POSIX terminology)
>>>
>>>     file-description locks
>>
>> I'd use file-handle, file-description or at least something that's
>> not associated to the "file" itself.
>>
>> file-handle-associated or file-description-associated would also work.
>>
> 
> Yeah, I understand your point.
> 
> I'm not keen on using "file-handle" as file handles have a completely
> different meaning in the context of something like NFS.
> 
> "file-description-associated" is rather a mouthful. You Germans might
> go for that sort of thing, but it feels awkward to us knuckle-draggers
> that primarily speak English.

Even as a knuckle-dragger in the German-speaking world it feels like
a mouthful ;-). But, I think Stefan's preference is anyway for the 
shorter term(s), IIUC.

> Maybe we should just go with one of Michael's earlier suggestions --
> "file-description locks" and change the macros to F_FD_*.

>From my perspective, and the few comments so far, "file-handle lock"
or "file-description lock" seems the way to go. I imagine some will
not be so happy with the latter term (because unfamiliar and
too similar to "file descriptor), but the open(2) man page has for 
quite a long time now (9+ years) has followed POSIX in using the term
"open file description".

> In the docs we could take pains to point out that these are
> file-_description_ locks and not file-_descriptor_ locks, and outline
> why that is so (which is something I'm trying to make crystal clear in
> the docs anyway).
> 
> Does anyone object to that?

Well, I'd be silly to object, but maybe we should still allow a day 
for further comment?

Cheers,

Michael


>>> but that last might be a bit confusing to people who are not
>>> standards-aware. (The POSIX standard defines the thing that a "file
>>> descriptor" refers to as a "file description"; other people often call
>>> that thing a "file handle" or an "open file table entry" or a "struct
>>> file". The POSIX term is precise and unambiguous, but, unfortunately,
>>> the term is not common outside the standard and is also easily
>>> mistaken for "file descriptor".)
>>>
>>>> At the same time, he suggested that we rename the command macros since
>>>> the 'P' suffix would no longer be relevant. He suggested something like
>>>> this:
>>>>
>>>>     F_FA_GETLK
>>>>     F_FA_SETLK
>>>>     F_FA_SETLKW
>>
>> With file-description-associated this could be
>>
>> F_FDA_*
>>
>> metze
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: should we change the name/macros of file-private locks?

[Stefan (metze) Metzmacher]

Am 17.04.2014 13:52, schrieb Jeff Layton:
> On Thu, 17 Apr 2014 00:42:13 +0200
> "Stefan (metze) Metzmacher" <metze@samba.org> wrote:
> 
>> Am 16.04.2014 22:00, schrieb Michael Kerrisk (man-pages):
>>> [CC += Jeremy Allison]
>>>
>>> On Wed, Apr 16, 2014 at 8:57 PM, Jeff Layton <jlayton@redhat.com> wrote:
>>>> Sorry to spam so many lists, but I think this needs widespread
>>>> distribution and consensus.
>>>>
>>>> File-private locks have been merged into Linux for v3.15, and *now*
>>>> people are commenting that the name and macro definitions for the new
>>>> file-private locks suck.
>>>>
>>>> ...and I can't even disagree. They do suck.
>>>>
>>>> We're going to have to live with these for a long time, so it's
>>>> important that we be happy with the names before we're stuck with them.
>>>
>>> So, to add my perspective: 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.
>>>
>>>> Michael Kerrisk suggested several names but I think the only one that
>>>> doesn't have other issues is "file-associated locks", which can be
>>>> distinguished against "process-associated" locks (aka classic POSIX
>>>> locks).
>>>
>>> The names I have suggested are:
>>>
>>>     file-associated locks
>>>
>>> or
>>>
>>>    file-handle locks
>>>
>>> or (using POSIX terminology)
>>>
>>>     file-description locks
>>
>> I'd use file-handle, file-description or at least something that's
>> not associated to the "file" itself.
>>
>> file-handle-associated or file-description-associated would also work.
>>
> 
> Yeah, I understand your point.
> 
> I'm not keen on using "file-handle" as file handles have a completely
> different meaning in the context of something like NFS.
> 
> "file-description-associated" is rather a mouthful. You Germans might
> go for that sort of thing, but it feels awkward to us knuckle-draggers
> that primarily speak English.
> 
> Maybe we should just go with one of Michael's earlier suggestions --
> "file-description locks" and change the macros to F_FD_*.
> 
> In the docs we could take pains to point out that these are
> file-_description_ locks and not file-_descriptor_ locks, and outline
> why that is so (which is something I'm trying to make crystal clear in
> the docs anyway).
> 
> Does anyone object to that?

Sounds good.

metze

Re: should we change the name/macros of file-private locks?

[Michael Kerrisk (man-pages)]

>> In the docs we could take pains to point out that these are
>> file-_description_ locks and not file-_descriptor_ locks, and outline
>> why that is so (which is something I'm trying to make crystal clear in
>> the docs anyway).
>>
>> Does anyone object to that?
>
> Well, I'd be silly to object, but maybe we should still allow a day
> for further comment?

Jeff,

One further point. I know the intent is to get this scheme into POSIX.
Have any conversations happened about this so far on the POSIX/Austin
lists? If yes, it might be worth also linking those folks into the
naming discussion..

Cheers,

Michael

Re: should we change the name/macros of file-private locks?

[Jeff Layton]

On Thu, 17 Apr 2014 22:08:54 +0200
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> wrote:

> >> In the docs we could take pains to point out that these are
> >> file-_description_ locks and not file-_descriptor_ locks, and outline
> >> why that is so (which is something I'm trying to make crystal clear in
> >> the docs anyway).
> >>
> >> Does anyone object to that?
> >
> > Well, I'd be silly to object, but maybe we should still allow a day
> > for further comment?
> 
> Jeff,
> 
> One further point. I know the intent is to get this scheme into POSIX.
> Have any conversations happened about this so far on the POSIX/Austin
> lists? If yes, it might be worth also linking those folks into the
> naming discussion..
> 
> Cheers,
> 
> Michael

Yes, good idea. The open bug is here:

    http://austingroupbugs.net/view.php?id=768

I'll write something up there and see if they want to chime in on the
discussion.

-- 
Jeff Layton <jlayton@redhat.com>