Re: git: 2c2ef670a79b - main - pseudofs: use the vget_prep/vget_finish idiom

On Sat, Sep 24, 2022 at 09:20:13PM +0200, Mateusz Guzik wrote:
> On 9/24/22, Benjamin Kaduk <bjkfbsd@gmail.com> wrote:
> > On Thu, Sep 22, 2022 at 3:11 AM Mateusz Guzik <mjguzik@gmail.com> wrote:
> >
> >> On 9/19/22, Benjamin Kaduk <bjkfbsd@gmail.com> wrote:
> >> > On Mon, Sep 19, 2022 at 1:09 PM Mateusz Guzik <mjg@freebsd.org> wrote:
> >> >
> >> >> The branch main has been updated by mjg:
> >> >>
> >> >> URL:
> >> >>
> >> https://cgit.FreeBSD.org/src/commit/?id=2c2ef670a79b7f8fa84796a04885a3f76c914762
> >> >>
> >> >> commit 2c2ef670a79b7f8fa84796a04885a3f76c914762
> >> >> Author:     Mateusz Guzik <mjg@FreeBSD.org>
> >> >> AuthorDate: 2022-09-19 20:07:10 +0000
> >> >> Commit:     Mateusz Guzik <mjg@FreeBSD.org>
> >> >> CommitDate: 2022-09-19 20:08:40 +0000
> >> >>
> >> >>     pseudofs: use the vget_prep/vget_finish idiom
> >> >>
> >> >>
> >> >
> >> > Picking an arbitrary commit to reply to: could you please add a bit
> >> > more
> >> > detail about the "why" to commit messages in the future?
> >> > Having looked a little bit, it seems that this would be "as part of the
> >> > broader effort to remove the vnode interlock [from a specific class of
> >> > operations?]".  A pointer to a bigger-picture doc would be great as
> >> > well.
> >>
> >> The idiom at hand is over 3 years old now and employing it at this
> >> point should not require a justification.
> >>
> >> One can easily see not taking the interlock is faster both single- and
> >> multi-threaded, which makes the change worthwhile regardless of
> >> support for the flag in locking primitives going away or not.
> >>
> >>
> > Maybe you can easily see so, and maybe I can easily see so as well.
> > But it is not guaranteed to be the case for everyone looking at the commit
> > history.
> > The "what" of the commit is contained in the commit itself, but the "why"
> > can easily
> > be lost to the depths of time; that is why I see it as more important to
> > record in the commit
> > message.
> >
> 
> The what is to employ an in idiom, it being an idiom should require no
> justification in the commit message.
> 
> > Indeed, when I was left here to guess at the "why", I got it wrong!  So is
> > it so hard to add
> > another sentence or even a clause like "an easy microoptimization" to the
> > commit message?
> > Having some hint at the "why" greatly improves the quality of the record
> > that is the commit.
> >
> 
> What did you think it is?  VI_LOCK + vhold disappear in favor of
> vget_prep, quick look inside shows there is no interlock taken
> whatsoever and that's how one finds out it gets avoided. Performance
> implications should be obvious from that point.
> 
> The way I see it extra content in this case decreases the quality
> significantly. Anyone familiar with the idiom can comfortably skip
> this commit while browsing the history because the one liner indicates
> there is nothing more to it. Should extra sentences be present it
> would suggest something non-standard is going on and attention is
> required, when it is not. It's equivalent to adding comments like "/*
> free the buffer */" just prior to "free(buf);". Anyone not familiar
> with the idiom can quickly find out what it is. Explaining something
> like this every single time a change of the sort is made makes no
> sense to me whatsoever.
I completely disagree.  Commit message must include the justification
why the change is correct, in this case.  If not to teach the reader
why, then at least to allow the reader to clearly agree or not with
the justification.

I believe this rule is required for any changes that modify synchronization.