inside your C function are
   reclaimed at C function exit, avoiding memory leakage.
  </para>

  <para>
   However, if your C function 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 <function>palloc</function>, at
   least not while you are connected to SPI.  If you try, the object
   will be deallocated by <function>SPI_finish</function>, and your
   C function will not work reliably.  To solve this problem, use
   <function>SPI_palloc</function> to allocate memory for your return
   object.  <function>SPI_palloc</function> allocates memory in the
   <quote>upper executor context</quote>, that is, the memory context
   that was current when <function>SPI_connect</function> was called,
   which is precisely the right context for a value returned from your
   C function.  Several of the other utility functions described in
   this section also return objects created in the upper executor context.
  </para>

  <para>
   When <function>SPI_connect</function> is called, the private
   context of the C function, which is created by
   <function>SPI_connect</function>, is made the current context.  All
   allocations made by <function>palloc</function>,
   <function>repalloc</function>, or SPI utility functions (except as
   described in this section) are made in this context.  When a
   C function disconnects from the SPI manager (via
   <function>SPI_finish</function>) the current context is restored to
   the upper executor context, and all allocations made in the
   C function memory context are freed and cannot be used any more.
  </para>

<!-- *********************************************** -->

<refentry id="spi-spi-palloc">
 <indexterm><primary>SPI_palloc</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_palloc</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_palloc</refname>
  <refpurpose>allocate memory in the upper executor context</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
void * SPI_palloc(Size <parameter>size</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_palloc</function> allocates memory in the upper
   executor context.
  </para>

  <para>
   This function can only be used while connected to SPI.
   Otherwise, it throws an error.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Size <parameter>size</parameter></literal></term>
    <listitem>
     <para>
      size in bytes of storage to allocate
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   pointer to new storage space of the specified size
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-realloc">
 <indexterm><primary>SPI_repalloc</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_repalloc</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_repalloc</refname>
  <refpurpose>reallocate memory in the upper executor context</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
void * SPI_repalloc(void * <parameter>pointer</parameter>, Size <parameter>size</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_repalloc</function> changes the size of a memory
   segment previously allocated using <function>SPI_palloc</function>.
  </para>

  <para>
   This function is no longer different from plain
   <function>repalloc</function>.  It's kept just for backward
   compatibility of existing code.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>pointer</parameter></literal></term>
    <listitem>
     <para>
      pointer to existing storage to change
     </para>