begriffs open source - ai-pg/blob - full-docs/txt/spi-memory.txt

   1
   2 45.3. Memory Management #
   3
   4    SPI_palloc — allocate memory in the upper executor context
   5    SPI_repalloc — reallocate memory in the upper executor context
   6    SPI_pfree — free memory in the upper executor context
   7    SPI_copytuple — make a copy of a row in the upper executor context
   8    SPI_returntuple — prepare to return a tuple as a Datum
   9    SPI_modifytuple — create a row by replacing selected fields of a given
  10           row
  11
  12    SPI_freetuple — free a row allocated in the upper executor context
  13    SPI_freetuptable — free a row set created by SPI_execute or a similar
  14           function
  15
  16    SPI_freeplan — free a previously saved prepared statement
  17
  18    PostgreSQL allocates memory within memory contexts, which provide a
  19    convenient method of managing allocations made in many different places
  20    that need to live for differing amounts of time. Destroying a context
  21    releases all the memory that was allocated in it. Thus, it is not
  22    necessary to keep track of individual objects to avoid memory leaks;
  23    instead only a relatively small number of contexts have to be managed.
  24    palloc and related functions allocate memory from the “current”
  25    context.
  26
  27    SPI_connect creates a new memory context and makes it current.
  28    SPI_finish restores the previous current memory context and destroys
  29    the context created by SPI_connect. These actions ensure that transient
  30    memory allocations made inside your C function are reclaimed at C
  31    function exit, avoiding memory leakage.
  32
  33    However, if your C function needs to return an object in allocated
  34    memory (such as a value of a pass-by-reference data type), you cannot
  35    allocate that memory using palloc, at least not while you are connected
  36    to SPI. If you try, the object will be deallocated by SPI_finish, and
  37    your C function will not work reliably. To solve this problem, use
  38    SPI_palloc to allocate memory for your return object. SPI_palloc
  39    allocates memory in the “upper executor context”, that is, the memory
  40    context that was current when SPI_connect was called, which is
  41    precisely the right context for a value returned from your C function.
  42    Several of the other utility functions described in this section also
  43    return objects created in the upper executor context.
  44
  45    When SPI_connect is called, the private context of the C function,
  46    which is created by SPI_connect, is made the current context. All
  47    allocations made by palloc, repalloc, or SPI utility functions (except
  48    as described in this section) are made in this context. When a C
  49    function disconnects from the SPI manager (via SPI_finish) the current
  50    context is restored to the upper executor context, and all allocations
  51    made in the C function memory context are freed and cannot be used any
  52    more.