Horton

Thread

Commits

  1. doc: Fix explanation related to pg_shmem_allocations

  1. pg_shmem_allocations & documentation

    Benoit Lobréau <benoit.lobreau@gmail.com> — 2020-12-10T10:07:47Z

    Hi,

While reading the documentation of pg_shmem_allocations, I noticed that the
off column is described as such :

"The offset at which the allocation starts. NULL for anonymous allocations
and unused memory."

Whereas, the view returns a value for unused memory:

[local]:5433 postgres@postgres=# SELECT * FROM pg_shmem_allocations WHERE
name IS NULL;
 name |    off    |  size   | allocated_size
------+-----------+---------+----------------
 ¤    | 178095232 | 1923968 |        1923968
(1 row)

From what I understand, the doc is wrong.
Am I right ?

Benoit

[1] https://www.postgresql.org/docs/13/view-pg-shmem-allocations.html
[2]
https://www.postgresql.org/message-id/flat/20140504114417.GM12715%40awork2.anarazel.de
(original thread)

  2. Re: pg_shmem_allocations & documentation

    Kyotaro Horiguchi <horikyota.ntt@gmail.com> — 2020-12-11T02:00:58Z

    At Thu, 10 Dec 2020 11:07:47 +0100, Benoit Lobréau <benoit.lobreau@gmail.com> wrote in 
> Hi,
> 
> While reading the documentation of pg_shmem_allocations, I noticed that the
> off column is described as such :
> 
> "The offset at which the allocation starts. NULL for anonymous allocations
> and unused memory."
> 
> Whereas, the view returns a value for unused memory:
> 
> [local]:5433 postgres@postgres=# SELECT * FROM pg_shmem_allocations WHERE
> name IS NULL;
>  name |    off    |  size   | allocated_size
> ------+-----------+---------+----------------
>  ¤    | 178095232 | 1923968 |        1923968
> (1 row)
> 
> From what I understand, the doc is wrong.
> Am I right ?

Good catch! I think you're right.  It seems to me the conclusion in
the discussion is to expose the offset for free memory.

Although we could just rip some words off, I'd like to propose instead
to add an explanation why it is not exposed for anonymous allocations,
like the column allocated_size.

> Benoit
> 
> [1] https://www.postgresql.org/docs/13/view-pg-shmem-allocations.html
> [2]
> https://www.postgresql.org/message-id/flat/20140504114417.GM12715%40awork2.anarazel.de
> (original thread)

regards.
¤
-- 
Kyotaro Horiguchi
NTT Open Source Software Center

  3. Re: pg_shmem_allocations & documentation

    Michael Paquier <michael@paquier.xyz> — 2020-12-11T05:42:45Z

    On Fri, Dec 11, 2020 at 11:00:58AM +0900, Kyotaro Horiguchi wrote:
> Although we could just rip some words off, I'd like to propose instead
> to add an explanation why it is not exposed for anonymous allocations,
> like the column allocated_size.

Indeed, there is a hiccup between what the code does and what the docs
tell: the offset is not NULL for unused memory.

> -       The offset at which the allocation starts. NULL for anonymous
> -       allocations and unused memory.
> +       The offset at which the allocation starts. For anonymous allocations,
> +       no information about individual allocations is available, so the column
> +       will be NULL in that case.

I'd say: let's be simple and just remove "and unused memory" because
anonymous allocations are...  Anonymous so you cannot know details
related to them.  That's something easy to reason about, and the docs
were written originally to remain simple.
--
Michael

  4. Re: pg_shmem_allocations & documentation

    Kyotaro Horiguchi <horikyota.ntt@gmail.com> — 2020-12-11T08:29:54Z

    At Fri, 11 Dec 2020 14:42:45 +0900, Michael Paquier <michael@paquier.xyz> wrote in 
> On Fri, Dec 11, 2020 at 11:00:58AM +0900, Kyotaro Horiguchi wrote:
> > Although we could just rip some words off, I'd like to propose instead
> > to add an explanation why it is not exposed for anonymous allocations,
> > like the column allocated_size.
> 
> Indeed, there is a hiccup between what the code does and what the docs
> tell: the offset is not NULL for unused memory.
> 
> > -       The offset at which the allocation starts. NULL for anonymous
> > -       allocations and unused memory.
> > +       The offset at which the allocation starts. For anonymous allocations,
> > +       no information about individual allocations is available, so the column
> > +       will be NULL in that case.
> 
> I'd say: let's be simple and just remove "and unused memory" because
> anonymous allocations are...  Anonymous so you cannot know details
> related to them.  That's something easy to reason about, and the docs
> were written originally to remain simple.

Hmm. I don't object to that.  Howerver, isn't the description for
allocated_size too verbose in that sense?

regards.

-- 
Kyotaro Horiguchi
NTT Open Source Software Center

  5. Re: pg_shmem_allocations & documentation

    Benoit Lobréau <benoit.lobreau@gmail.com> — 2020-12-11T08:58:29Z

    Would "NULL for anonymous allocations, since details related to them are
not known." be ok ?


Le ven. 11 déc. 2020 à 09:29, Kyotaro Horiguchi <horikyota.ntt@gmail.com> a
écrit :

> At Fri, 11 Dec 2020 14:42:45 +0900, Michael Paquier <michael@paquier.xyz>
> wrote in
> > On Fri, Dec 11, 2020 at 11:00:58AM +0900, Kyotaro Horiguchi wrote:
> > > Although we could just rip some words off, I'd like to propose instead
> > > to add an explanation why it is not exposed for anonymous allocations,
> > > like the column allocated_size.
> >
> > Indeed, there is a hiccup between what the code does and what the docs
> > tell: the offset is not NULL for unused memory.
> >
> > > -       The offset at which the allocation starts. NULL for anonymous
> > > -       allocations and unused memory.
> > > +       The offset at which the allocation starts. For anonymous
> allocations,
> > > +       no information about individual allocations is available, so
> the column
> > > +       will be NULL in that case.
> >
> > I'd say: let's be simple and just remove "and unused memory" because
> > anonymous allocations are...  Anonymous so you cannot know details
> > related to them.  That's something easy to reason about, and the docs
> > were written originally to remain simple.
>
> Hmm. I don't object to that.  Howerver, isn't the description for
> allocated_size too verbose in that sense?
>
> regards.
>
> --
> Kyotaro Horiguchi
> NTT Open Source Software Center
>

  6. Re: pg_shmem_allocations & documentation

    Benoit Lobréau <benoit.lobreau@gmail.com> — 2020-12-14T09:33:06Z

    Here's a proposal patch.

Le ven. 11 déc. 2020 à 09:58, Benoit Lobréau <benoit.lobreau@gmail.com> a
écrit :

> Would "NULL for anonymous allocations, since details related to them are
> not known." be ok ?
>
>
> Le ven. 11 déc. 2020 à 09:29, Kyotaro Horiguchi <horikyota.ntt@gmail.com>
> a écrit :
>
>> At Fri, 11 Dec 2020 14:42:45 +0900, Michael Paquier <michael@paquier.xyz>
>> wrote in
>> > On Fri, Dec 11, 2020 at 11:00:58AM +0900, Kyotaro Horiguchi wrote:
>> > > Although we could just rip some words off, I'd like to propose instead
>> > > to add an explanation why it is not exposed for anonymous allocations,
>> > > like the column allocated_size.
>> >
>> > Indeed, there is a hiccup between what the code does and what the docs
>> > tell: the offset is not NULL for unused memory.
>> >
>> > > -       The offset at which the allocation starts. NULL for anonymous
>> > > -       allocations and unused memory.
>> > > +       The offset at which the allocation starts. For anonymous
>> allocations,
>> > > +       no information about individual allocations is available, so
>> the column
>> > > +       will be NULL in that case.
>> >
>> > I'd say: let's be simple and just remove "and unused memory" because
>> > anonymous allocations are...  Anonymous so you cannot know details
>> > related to them.  That's something easy to reason about, and the docs
>> > were written originally to remain simple.
>>
>> Hmm. I don't object to that.  Howerver, isn't the description for
>> allocated_size too verbose in that sense?
>>
>> regards.
>>
>> --
>> Kyotaro Horiguchi
>> NTT Open Source Software Center
>>
>

  7. Re: pg_shmem_allocations & documentation

    Michael Paquier <michael@paquier.xyz> — 2020-12-15T01:09:35Z

    On Mon, Dec 14, 2020 at 10:33:06AM +0100, Benoit Lobréau wrote:
>        </para>
>        <para>
>         The offset at which the allocation starts. NULL for anonymous
> -       allocations and unused memory.
> +       allocations, since details related to them are not known.
>        </para></entry>

Both of you seem to agree about having more details about that, which
is fine by me at the end.  Horiguchi-san, do you have more thoughts to
offer?  Benoit's version is similar to yours, just simpler.
--
Michael

  8. Re: pg_shmem_allocations & documentation

    Michael Paquier <michael@paquier.xyz> — 2020-12-16T01:40:43Z

    On Tue, Dec 15, 2020 at 10:09:35AM +0900, Michael Paquier wrote:
> Both of you seem to agree about having more details about that, which
> is fine by me at the end.  Horiguchi-san, do you have more thoughts to
> offer?  Benoit's version is similar to yours, just simpler.

Okay, applied this one then.  Thanks Benoit and Horigushi-san.
--
Michael