Re: Fix comments for buf_id field of BufferDesc structure

> On Jan 20, 2026, at 14:35, Daniil Davydov <3danissimo(at)gmail(dot)com> wrote:
>
> Hi,
>
> I noticed that the BufferDesc structure contains the following field
> and a comment :
>
> /*
> * Buffer's index number (from 0). The field never changes after
> * initialization, so does not need locking.
> */
> int buf_id;
>
> Actually, the comment is wrong, because we are using negative ids for
> local buffers (i.e. "buf_id" field contains values -1, -2, and so on). We
> have a comment about it in localbuf.c :
>
> /*
> * negative to indicate local buffer. This is tricky: shared buffers
> * start with 0. We have to start with -2. (Note that the routine
> * BufferDescriptorGetBuffer adds 1 to buf_id so our first buffer id
> * is -1.)
> */
>
> Maybe we should place this note in buf_internals.h? Anyone who
> wants to know what this field means will look at the comment in
> buf_internals.h and be misled.
>
> I have attached a patch with my suggestion. What do you think?
>
> --
> Best regards,
> Daniil Davydov
> <0001-Fix-comment-in-BufferDesc-struct.patch>

Good catch. But I think we should retain the explanation for -2. How about like:

For buf_internal.h:
```
/*
* Buffer's index number: >= 0 for shared buffers, < -1 for local buffers.
* * For shared buffers, buf_id is 0 to NBuffers-1.
* * For local buffers, buf_id is -2 to -NLocBuffers-1.
*
* This ensures that (buf_id+1) done by BufferDescriptorGetBuffer never returns InvalidBuffer(0).
*/
int buf_id;
```

For localbuf.c
```
/*
* buf_id must be <= -2 for local buffers so that the
* Buffer handle (buf_id + 1) is <= -1, avoiding InvalidBuffer (0)
*/
```

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/