| Current File : //usr/share/doc/postgresql-9.2.24/html/spi-memory.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Memory Management</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.2.24 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Server Programming Interface"
HREF="spi.html"><LINK
REL="PREVIOUS"
TITLE="SPI_getnspname"
HREF="spi-spi-getnspname.html"><LINK
REL="NEXT"
TITLE="SPI_palloc"
HREF="spi-spi-palloc.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2017-11-06T22:43:11"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.2.24 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="SPI_getnspname"
HREF="spi-spi-getnspname.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="spi.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 43. Server Programming Interface</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="SPI_palloc"
HREF="spi-spi-palloc.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="SPI-MEMORY"
>43.3. Memory Management</A
></H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="spi-spi-palloc.html"
>SPI_palloc</A
> -- allocate memory in the upper executor context</DT
><DT
><A
HREF="spi-realloc.html"
>SPI_repalloc</A
> -- reallocate memory in the upper executor context</DT
><DT
><A
HREF="spi-spi-pfree.html"
>SPI_pfree</A
> -- free memory in the upper executor context</DT
><DT
><A
HREF="spi-spi-copytuple.html"
>SPI_copytuple</A
> -- make a copy of a row in the upper executor context</DT
><DT
><A
HREF="spi-spi-returntuple.html"
>SPI_returntuple</A
> -- prepare to return a tuple as a Datum</DT
><DT
><A
HREF="spi-spi-modifytuple.html"
>SPI_modifytuple</A
> -- create a row by replacing selected fields of a given row</DT
><DT
><A
HREF="spi-spi-freetuple.html"
>SPI_freetuple</A
> -- free a row allocated in the upper executor context</DT
><DT
><A
HREF="spi-spi-freetupletable.html"
>SPI_freetuptable</A
> -- free a row set created by <CODE
CLASS="FUNCTION"
>SPI_execute</CODE
> or a similar
function</DT
><DT
><A
HREF="spi-spi-freeplan.html"
>SPI_freeplan</A
> -- free a previously saved prepared statement</DT
></DL
></DIV
><P
>
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> allocates memory within
<I
CLASS="FIRSTTERM"
>memory contexts</I
>, 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.
<CODE
CLASS="FUNCTION"
>palloc</CODE
> and related functions allocate memory
from the <SPAN
CLASS="QUOTE"
>"current"</SPAN
> context.
</P
><P
> <CODE
CLASS="FUNCTION"
>SPI_connect</CODE
> creates a new memory context and
makes it current. <CODE
CLASS="FUNCTION"
>SPI_finish</CODE
> restores the
previous current memory context and destroys the context created by
<CODE
CLASS="FUNCTION"
>SPI_connect</CODE
>. These actions ensure that
transient memory allocations made inside your procedure are
reclaimed at procedure exit, avoiding memory leakage.
</P
><P
> 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 <CODE
CLASS="FUNCTION"
>palloc</CODE
>, at
least not while you are connected to SPI. If you try, the object
will be deallocated by <CODE
CLASS="FUNCTION"
>SPI_finish</CODE
>, and your
procedure will not work reliably. To solve this problem, use
<CODE
CLASS="FUNCTION"
>SPI_palloc</CODE
> to allocate memory for your return
object. <CODE
CLASS="FUNCTION"
>SPI_palloc</CODE
> allocates memory in the
<SPAN
CLASS="QUOTE"
>"upper executor context"</SPAN
>, that is, the memory context
that was current when <CODE
CLASS="FUNCTION"
>SPI_connect</CODE
> was called,
which is precisely the right context for a value returned from your
procedure.
</P
><P
> If <CODE
CLASS="FUNCTION"
>SPI_palloc</CODE
> is called while the procedure is
not connected to SPI, then it acts the same as a normal
<CODE
CLASS="FUNCTION"
>palloc</CODE
>. 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
<CODE
CLASS="FUNCTION"
>palloc</CODE
> or by SPI utility functions are made in
this context.
</P
><P
> When <CODE
CLASS="FUNCTION"
>SPI_connect</CODE
> is called, the private
context of the procedure, which is created by
<CODE
CLASS="FUNCTION"
>SPI_connect</CODE
>, is made the current context. All
allocations made by <CODE
CLASS="FUNCTION"
>palloc</CODE
>,
<CODE
CLASS="FUNCTION"
>repalloc</CODE
>, or SPI utility functions (except for
<CODE
CLASS="FUNCTION"
>SPI_copytuple</CODE
>,
<CODE
CLASS="FUNCTION"
>SPI_returntuple</CODE
>,
<CODE
CLASS="FUNCTION"
>SPI_modifytuple</CODE
>, and
<CODE
CLASS="FUNCTION"
>SPI_palloc</CODE
>) are made in this context. When a
procedure disconnects from the SPI manager (via
<CODE
CLASS="FUNCTION"
>SPI_finish</CODE
>) 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.
</P
><P
> All functions described in this section can be used by both
connected and unconnected procedures. In an unconnected procedure,
they act the same as the underlying ordinary server functions
(<CODE
CLASS="FUNCTION"
>palloc</CODE
>, etc.).
</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="spi-spi-getnspname.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="spi-spi-palloc.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SPI_getnspname</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="spi.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SPI_palloc</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>