- Table of Contents
- SPI_palloc -- allocate memory in the upper executor context
- SPI_repalloc -- reallocate memory in the upper executor context
- SPI_pfree -- free memory in the upper executor context
- SPI_copytuple -- make a copy of a row in the upper executor context
- SPI_returntuple -- prepare to return a tuple as a Datum
- SPI_modifytuple -- create a row by replacing selected fields of a given row
- SPI_freetuple -- free a row allocated in the upper executor context
- SPI_freetuptable -- free a row set created by
SPI_execute or a similar
function - SPI_freeplan -- free a previously saved plan
PostgreSQL allocates memory within
memory contexts, which provide a convenient method of
managing allocations made in many different places that need to
live for differing amounts of time. Destroying a context releases
all the memory that was allocated in it. Thus, it is not necessary
to keep track of individual objects to avoid memory leaks; instead
only a relatively small number of contexts have to be managed.
palloc and related functions allocate memory
from the "current" context.
SPI_connect creates a new memory context and
makes it current. SPI_finish restores the
previous current memory context and destroys the context created by
SPI_connect. These actions ensure that
transient memory allocations made inside your procedure are
reclaimed at procedure exit, avoiding memory leakage.
However, if your procedure needs to return an object in allocated
memory (such as a value of a pass-by-reference data type), you
cannot allocate that memory using palloc, at
least not while you are connected to SPI. If you try, the object
will be deallocated by SPI_finish, and your
procedure will not work reliably. To solve this problem, use
SPI_palloc to allocate memory for your return
object. SPI_palloc allocates memory in the
"upper executor context", that is, the memory context
that was current when SPI_connect was called,
which is precisely the right context for a value returned from your
procedure.
If SPI_palloc is called while the procedure is
not connected to SPI, then it acts the same as a normal
palloc. Before a procedure connects to the
SPI manager, the current memory context is the upper executor
context, so all allocations made by the procedure via
palloc or by SPI utility functions are made in
this context.
When SPI_connect is called, the private
context of the procedure, which is created by
SPI_connect, is made the current context. All
allocations made by palloc,
repalloc, or SPI utility functions (except for
SPI_copytuple,
SPI_returntuple,
SPI_modifytuple, and
SPI_palloc) are made in this context. When a
procedure disconnects from the SPI manager (via
SPI_finish) the current context is restored to
the upper executor context, and all allocations made in the
procedure memory context are freed and cannot be used any more.
All functions described in this section may be used by both
connected and unconnected procedures. In an unconnected procedure,
they act the same as the underlying ordinary server functions
(palloc, etc.).
