Обсуждение: Replace references to malloc() in libpq documentation with generic language

The commit message in the attached patch provides the reasoning, as follows:

The user does not benefit from knowing that libpq allocates some/all memory
using malloc(). Mentioning malloc() here has a few downsides, and almost no
benefits.

All the relevant mentions of malloc() are followed by an explicit
instruction to use PQfreemem() to free the resulting objects. So the
docs perform the sufficient job of educating the user on how to properly
free the memory.  But these mentions of malloc() may still lead an
inexperienced or careless user to (wrongly) believe that they may use
free() to free the resulting memory. They will be in a lot of pain until
they learn that (when linked statically) libpq's malloc()/free() cannot
be mixed with malloc()/free() of whichever malloc() library the client
application is being linked with.

Another downside of explicitly mentioning that objects returned by libpq
functions are allocated with malloc(), is that it exposes the implementation
details of libpq to the users. Such details are best left unmentioned so that
these can be freely changed in the future without having to worry about its
effect on client applications.

Whenever necessary, it is sufficient to tell the user that the objects/memory
returned by libpq functions is allocated on the heap. That is just enough
detail for the user to realize that the relevant object/memory needs to be
freed; and the instructions that follow mention to use PQfreemem() to free such
memory.

One mention of malloc is left intact, because that mention is unrelated to how
the memory is allocated, or how to free it.

In passing, slightly improve the language of PQencryptPasswordConn()
documentation.

Best regards,
Gurjeet
http://Gurje.et

> On 24 Oct 2023, at 07:13, Gurjeet Singh <gurjeet@singh.im> wrote:

> The user does not benefit from knowing that libpq allocates some/all memory
> using malloc(). Mentioning malloc() here has a few downsides, and almost no
> benefits.

I'm not entirely convinced that replacing "malloc" with "allocated on the heap"
improves the documentation.  I do agree with this proposed change though:

-      all the space that will be freed by <xref linkend="libpq-PQclear"/>.
+      all the memory that will be freed by <xref linkend="libpq-PQclear"/>.

--
Daniel Gustafsson

Daniel Gustafsson <daniel@yesql.se> writes:
>> On 24 Oct 2023, at 07:13, Gurjeet Singh <gurjeet@singh.im> wrote:
>> The user does not benefit from knowing that libpq allocates some/all memory
>> using malloc(). Mentioning malloc() here has a few downsides, and almost no
>> benefits.

> I'm not entirely convinced that replacing "malloc" with "allocated on the heap"
> improves the documentation.

That was my reaction too.  The underlying storage allocator *is* malloc,
and C programmers know what that is, and I don't see how obfuscating
that improves matters.  It's true that on the miserable excuse for a
platform that is Windows, you have to use PQfreemem because of
Microsoft's inability to supply a standards-compliant implementation
of malloc.  But I'm not inclined to let that tail wag the dog.

> I do agree with this proposed change though:

> -      all the space that will be freed by <xref linkend="libpq-PQclear"/>.
> +      all the memory that will be freed by <xref linkend="libpq-PQclear"/>.

+1, seems harmless.

            regards, tom lane

> On 24 Oct 2023, at 17:07, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Daniel Gustafsson <daniel@yesql.se> writes:

>> I do agree with this proposed change though:
>
>> -      all the space that will be freed by <xref linkend="libpq-PQclear"/>.
>> +      all the memory that will be freed by <xref linkend="libpq-PQclear"/>.
>
> +1, seems harmless.

I've pushed this part, skipping the rest.

--
Daniel Gustafsson