Re: buffer README is out of date

On Tue, Sep 01, 2015 at 12:33:26AM -0500, Jim Nasby wrote:
> On 8/29/15 5:52 PM, Jeff Janes wrote:
> >If 2 other backends have a pin, only the last one to drop it should do
> >the waking. I don't see a way they could both try to do the waking, the
> >interlock on the buffer header seems to prevent that. But if it did,
> >that would just be another way you could have a spurious wake-up, which
> >can already happen for other reasons. I don't think the spurious wake
> >up needs to be documented in the higher level README file.
>
> My concern is someone will read too much into "signal will occur ... count
> to 1" and think there's no other ways to be woken up. I realize I'm being
> pedantic here, but given the nasty race condition bugs we've had lately
> maybe it's warranted.

Fair concern. I'm not too worried in this instance, because I can't think of
a choice the caller would make differently based on such a misunderstanding.
Precise wakeup conditions are not really part of the LockBufferForCleanup()
API contract[1]. The submission seems to move this README in the right
direction, so I committed it with some changes:

1. s/clean up/cleanup/
2. remove patch-added trailing whitespace
3. re-add to the first sentence a citation of rule #5
4. say that recovery can use LockBufferForCleanup(); heap_xlog_clean() does so

[1] If there's more to improve, it might be to move finer implementation
details out of the README and into code comments.