Re: Replace references to malloc() in libpq documentation with generic language
> On 24 Oct 2023, at 17:07, Tom Lane wrote: > Daniel Gustafsson writes: >> I do agree with this proposed change though: > >> - all the space that will be freed by . >> + all the memory that will be freed by . > > +1, seems harmless. I've pushed this part, skipping the rest. -- Daniel Gustafsson
Re: Replace references to malloc() in libpq documentation with generic language
Daniel Gustafsson writes: >> On 24 Oct 2023, at 07:13, Gurjeet Singh 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 . > + all the memory that will be freed by . +1, seems harmless. regards, tom lane
Re: Replace references to malloc() in libpq documentation with generic language
> On 24 Oct 2023, at 07:13, Gurjeet Singh 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 . + all the memory that will be freed by . -- Daniel Gustafsson
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 v1-0001-Replace-references-to-malloc-in-libpq-documentati.patch Description: Binary data
