Thread: Bug #548: Misleading documentation of `palloc'

Holger Krug (hkrug@rationalizer.com) reports a bug with a severity of 2
The lower the number the more severe it is.

Short Description
Misleading documentation of `palloc'

Long Description
In section 12.5.6 "Writing Code" of the "PostgreSQL 7.2 Programmer's
Guide" the following is said:

"When allocating memory, use the PostgreSQL routines `palloc' and
`pfree' instead of the corresponding C library routines `malloc' and
`free'. The memory allocated by `palloc' will be freed automatically
at the end of each transaction, preventing memory leaks."

This is not actually wrong but *misleading*, because memory allocated by `palloc' in a user-defined server-side C
languagefunction is freed not only at transaction end but actually at the end of each TransactionCommand - or even
more:at the end of each expression evaluation. The reason is, that the `CurrentMemoryContext' used for the evaluation
ofsuch functions is `PlanExprContext', which is a 
child of `TransactionCommandContext', which is a child of
`TopTransactionContext'.

As a consequence is appears that, given the following situation:

- a user-defined function `get_pointer()' which allocates server
memory (with `palloc') and returns a pointer to it
- a user-defined function `get_data(pointer)' which gets the pointer
as an argument and returns the data saved at the allocated memory

it is possible to use `get_pointer()' and `get_data(pointer)' together
if used within one expression, but it is impossible to use them in two
different expressions:

- `get_data(get_pointer())' will work
- the following PLpgSQL command sequence won't work:

  DECLARE
    p pointer;
  BEGIN
    p := get_pointer();
    RETURN get_data(p);
  END;

I propose to make the documentation more concise in this point and to add a macro like:

#define palloc_tx(sz)  MemoryContextAlloc(TopTransactionContext, (sz))

for the convenience of the server-side programmer to be used for memory allocation in server-side functions, in cases
whenthe allocated memory shall be valid up to the end of the current transaction. 

Sample Code


No file was uploaded with this report

pgsql-bugs@postgresql.org writes:
> I propose to make the documentation more concise in this point and to
> add a macro like:

> #define palloc_tx(sz)  MemoryContextAlloc(TopTransactionContext, (sz))

I don't think it's a good idea to encourage people to allocate in
TopTransactionContext as a substitute for thought.  One of the main
reasons for developing the memory context mechanism was to get rid
of transaction-duration memory leaks.  People who want to allocate
storage that will outlive a single function call need to think about
exactly how long it needs to live and when/where/how it will be
released.

I agree that the particular paragraph you identified is oversimplified,
but the right thing is to fix the documentation not add another layer
of oversimplification.

            regards, tom lane

Developer's FAQ updated to:

    <P><I>palloc()</I> and <I>pfree()</I> are used in place of malloc()
    and free() because we find it easier to automatically free all
    memory allocated when a query completes. This assures us that all
    memory that was allocated gets freed even if we have lost track of
    where we allocated it. There are special non-query contexts that
    memory can be allocated in. These affect when the allocated memory
    is freed by the backend.</P>


---------------------------------------------------------------------------

pgsql-bugs@postgresql.org wrote:
> Holger Krug (hkrug@rationalizer.com) reports a bug with a severity of 2
> The lower the number the more severe it is.
>
> Short Description
> Misleading documentation of `palloc'
>
> Long Description
> In section 12.5.6 "Writing Code" of the "PostgreSQL 7.2 Programmer's
> Guide" the following is said:
>
> "When allocating memory, use the PostgreSQL routines `palloc' and
> `pfree' instead of the corresponding C library routines `malloc' and
> `free'. The memory allocated by `palloc' will be freed automatically
> at the end of each transaction, preventing memory leaks."
>
> This is not actually wrong but *misleading*, because memory allocated by `palloc' in a user-defined server-side C
languagefunction is freed not only at transaction end but actually at the end of each TransactionCommand - or even
more:at the end of each expression evaluation. The reason is, that the `CurrentMemoryContext' used for the evaluation
ofsuch functions is `PlanExprContext', which is a 
> child of `TransactionCommandContext', which is a child of
> `TopTransactionContext'.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026