I386LINUX/util/I386LINUX/doc/postgresql/html/spi-memory.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML
   3 ><HEAD
   4 ><TITLE
   5 >Memory Management</TITLE
   6 ><META
   7 NAME="GENERATOR"
   8 CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
   9 REV="MADE"
  10 HREF="mailto:pgsql-docs@postgresql.org"><LINK
  11 REL="HOME"
  12 TITLE="PostgreSQL 7.4.1 Documentation"
  13 HREF="index.html"><LINK
  14 REL="UP"
  15 TITLE="Server Programming Interface"
  16 HREF="spi.html"><LINK
  17 REL="PREVIOUS"
  18 TITLE="SPI_getrelname"
  19 HREF="spi-spi-getrelname.html"><LINK
  20 REL="NEXT"
  21 TITLE="SPI_palloc"
  22 HREF="spi-spi-palloc.html"><LINK
  23 REL="STYLESHEET"
  24 TYPE="text/css"
  25 HREF="stylesheet.css"><META
  26 NAME="creation"
  27 CONTENT="2003-12-22T03:48:47"></HEAD
  28 ><BODY
  29 CLASS="SECT1"
  30 ><DIV
  31 CLASS="NAVHEADER"
  32 ><TABLE
  33 SUMMARY="Header navigation table"
  34 WIDTH="100%"
  35 BORDER="0"
  36 CELLPADDING="0"
  37 CELLSPACING="0"
  38 ><TR
  39 ><TH
  40 COLSPAN="5"
  41 ALIGN="center"
  42 VALIGN="bottom"
  43 >PostgreSQL 7.4.1 Documentation</TH
  44 ></TR
  45 ><TR
  46 ><TD
  47 WIDTH="10%"
  48 ALIGN="left"
  49 VALIGN="top"
  50 ><A
  51 HREF="spi-spi-getrelname.html"
  52 ACCESSKEY="P"
  53 >Prev</A
  54 ></TD
  55 ><TD
  56 WIDTH="10%"
  57 ALIGN="left"
  58 VALIGN="top"
  59 ><A
  60 HREF="spi.html"
  61 >Fast Backward</A
  62 ></TD
  63 ><TD
  64 WIDTH="60%"
  65 ALIGN="center"
  66 VALIGN="bottom"
  67 >Chapter 41. Server Programming Interface</TD
  68 ><TD
  69 WIDTH="10%"
  70 ALIGN="right"
  71 VALIGN="top"
  72 ><A
  73 HREF="spi.html"
  74 >Fast Forward</A
  75 ></TD
  76 ><TD
  77 WIDTH="10%"
  78 ALIGN="right"
  79 VALIGN="top"
  80 ><A
  81 HREF="spi-spi-palloc.html"
  82 ACCESSKEY="N"
  83 >Next</A
  84 ></TD
  85 ></TR
  86 ></TABLE
  87 ><HR
  88 ALIGN="LEFT"
  89 WIDTH="100%"></DIV
  90 ><DIV
  91 CLASS="SECT1"
  92 ><H1
  93 CLASS="SECT1"
  94 ><A
  95 NAME="SPI-MEMORY"
  96 >41.3. Memory Management</A
  97 ></H1
  98 ><DIV
  99 CLASS="TOC"
 100 ><DL
 101 ><DT
 102 ><B
 103 >Table of Contents</B
 104 ></DT
 105 ><DT
 106 ><A
 107 HREF="spi-spi-palloc.html"
 108 >SPI_palloc</A
 109 >&nbsp;--&nbsp;allocate memory in the upper executor context</DT
 110 ><DT
 111 ><A
 112 HREF="spi-realloc.html"
 113 >SPI_repalloc</A
 114 >&nbsp;--&nbsp;reallocate memory in the upper executor context</DT
 115 ><DT
 116 ><A
 117 HREF="spi-spi-pfree.html"
 118 >SPI_pfree</A
 119 >&nbsp;--&nbsp;free memory in the upper executor context</DT
 120 ><DT
 121 ><A
 122 HREF="spi-spi-copytuple.html"
 123 >SPI_copytuple</A
 124 >&nbsp;--&nbsp;make a copy of a row in the upper executor context</DT
 125 ><DT
 126 ><A
 127 HREF="spi-spi-copytupledesc.html"
 128 >SPI_copytupledesc</A
 129 >&nbsp;--&nbsp;make a copy of a row descriptor in the upper executor context</DT
 130 ><DT
 131 ><A
 132 HREF="spi-spi-copytupleintoslot.html"
 133 >SPI_copytupleintoslot</A
 134 >&nbsp;--&nbsp;make a copy of a row and descriptor in the upper executor context</DT
 135 ><DT
 136 ><A
 137 HREF="spi-spi-modifytuple.html"
 138 >SPI_modifytuple</A
 139 >&nbsp;--&nbsp;create a row by replacing selected fields of a given row</DT
 140 ><DT
 141 ><A
 142 HREF="spi-spi-freetuple.html"
 143 >SPI_freetuple</A
 144 >&nbsp;--&nbsp;frees a row allocated in the upper executor context</DT
 145 ><DT
 146 ><A
 147 HREF="spi-spi-freetupletable.html"
 148 >SPI_freetuptable</A
 149 >&nbsp;--&nbsp;free a row set created by <CODE
 150 CLASS="FUNCTION"
 151 >SPI_exec</CODE
 152 > or a similar function</DT
 153 ><DT
 154 ><A
 155 HREF="spi-spi-freeplan.html"
 156 >SPI_freeplan</A
 157 >&nbsp;--&nbsp;free a previously saved plan</DT
 158 ></DL
 159 ></DIV
 160 ><P
 161 >   <SPAN
 162 CLASS="PRODUCTNAME"
 163 >PostgreSQL</SPAN
 164 > allocates memory within
 165    <I
 166 CLASS="FIRSTTERM"
 167 >memory contexts</I
 168 ><A
 169 NAME="AEN34101"
 170 ></A
 171 >, which provide a convenient method of
 172    managing allocations made in many different places that need to
 173    live for differing amounts of time.  Destroying a context releases
 174    all the memory that was allocated in it.  Thus, it is not necessary
 175    to keep track of individual objects to avoid memory leaks; instead
 176    only a relatively small number of contexts have to be managed.
 177    <CODE
 178 CLASS="FUNCTION"
 179 >palloc</CODE
 180 > and related functions allocate memory
 181    from the <SPAN
 182 CLASS="QUOTE"
 183 >"current"</SPAN
 184 > context.
 185   </P
 186 ><P
 187 >   <CODE
 188 CLASS="FUNCTION"
 189 >SPI_connect</CODE
 190 > creates a new memory context and
 191    makes it current.  <CODE
 192 CLASS="FUNCTION"
 193 >SPI_finish</CODE
 194 > restores the
 195    previous current memory context and destroys the context created by
 196    <CODE
 197 CLASS="FUNCTION"
 198 >SPI_connect</CODE
 199 >.  These actions ensure that
 200    transient memory allocations made inside your procedure are
 201    reclaimed at procedure exit, avoiding memory leakage.
 202   </P
 203 ><P
 204 >   However, if your procedure needs to return an object in allocated
 205    memory (such as a value of a pass-by-reference data type), you
 206    cannot allocate that memory using <CODE
 207 CLASS="FUNCTION"
 208 >palloc</CODE
 209 >, at
 210    least not while you are connected to SPI.  If you try, the object
 211    will be deallocated by <CODE
 212 CLASS="FUNCTION"
 213 >SPI_finish</CODE
 214 >, and your
 215    procedure will not work reliably.  To solve this problem, use
 216    <CODE
 217 CLASS="FUNCTION"
 218 >SPI_palloc</CODE
 219 > to allocate memory for your return
 220    object.  <CODE
 221 CLASS="FUNCTION"
 222 >SPI_palloc</CODE
 223 > allocates memory in the
 224    <SPAN
 225 CLASS="QUOTE"
 226 >"upper executor context"</SPAN
 227 >, that is, the memory context
 228    that was current when <CODE
 229 CLASS="FUNCTION"
 230 >SPI_connect</CODE
 231 > was called,
 232    which is precisely the right context for return a value from your
 233    procedure.
 234   </P
 235 ><P
 236 >   If <CODE
 237 CLASS="FUNCTION"
 238 >SPI_palloc</CODE
 239 > is called while the procedure is
 240    not connected to SPI, then it acts the same as a normal
 241    <CODE
 242 CLASS="FUNCTION"
 243 >palloc</CODE
 244 >.  Before a procedure connects to the
 245    SPI manager, the current memory context is the upper executor
 246    context, so all allocations made by the procedure via
 247    <CODE
 248 CLASS="FUNCTION"
 249 >palloc</CODE
 250 > or by SPI utility functions are made in
 251    this context.
 252   </P
 253 ><P
 254 >   When <CODE
 255 CLASS="FUNCTION"
 256 >SPI_connect</CODE
 257 > is called, the private
 258    context of the procedure, which is created by
 259    <CODE
 260 CLASS="FUNCTION"
 261 >SPI_connect</CODE
 262 >, is made the current context.  All
 263    allocations made by <CODE
 264 CLASS="FUNCTION"
 265 >palloc</CODE
 266 >,
 267    <CODE
 268 CLASS="FUNCTION"
 269 >repalloc</CODE
 270 >, or SPI utility functions (except for
 271    <CODE
 272 CLASS="FUNCTION"
 273 >SPI_copytuple</CODE
 274 >,
 275    <CODE
 276 CLASS="FUNCTION"
 277 >SPI_copytupledesc</CODE
 278 >,
 279    <CODE
 280 CLASS="FUNCTION"
 281 >SPI_copytupleintoslot</CODE
 282 >,
 283    <CODE
 284 CLASS="FUNCTION"
 285 >SPI_modifytuple</CODE
 286 >, and
 287    <CODE
 288 CLASS="FUNCTION"
 289 >SPI_palloc</CODE
 290 >) are made in this context.  When a
 291    procedure disconnects from the SPI manager (via
 292    <CODE
 293 CLASS="FUNCTION"
 294 >SPI_finish</CODE
 295 >) the current context is restored to
 296    the upper executor context, and all allocations made in the
 297    procedure memory context are freed and cannot be used any more.
 298   </P
 299 ><P
 300 >   All functions described in this section may be used by both
 301    connected and unconnected procedures.  In an unconnected procedure,
 302    they act the same as the underlying ordinary server functions
 303    (<CODE
 304 CLASS="FUNCTION"
 305 >palloc</CODE
 306 >, etc.).
 307   </P
 308 ></DIV
 309 ><DIV
 310 CLASS="NAVFOOTER"
 311 ><HR
 312 ALIGN="LEFT"
 313 WIDTH="100%"><TABLE
 314 SUMMARY="Footer navigation table"
 315 WIDTH="100%"
 316 BORDER="0"
 317 CELLPADDING="0"
 318 CELLSPACING="0"
 319 ><TR
 320 ><TD
 321 WIDTH="33%"
 322 ALIGN="left"
 323 VALIGN="top"
 324 ><A
 325 HREF="spi-spi-getrelname.html"
 326 ACCESSKEY="P"
 327 >Prev</A
 328 ></TD
 329 ><TD
 330 WIDTH="34%"
 331 ALIGN="center"
 332 VALIGN="top"
 333 ><A
 334 HREF="index.html"
 335 ACCESSKEY="H"
 336 >Home</A
 337 ></TD
 338 ><TD
 339 WIDTH="33%"
 340 ALIGN="right"
 341 VALIGN="top"
 342 ><A
 343 HREF="spi-spi-palloc.html"
 344 ACCESSKEY="N"
 345 >Next</A
 346 ></TD
 347 ></TR
 348 ><TR
 349 ><TD
 350 WIDTH="33%"
 351 ALIGN="left"
 352 VALIGN="top"
 353 >SPI_getrelname</TD
 354 ><TD
 355 WIDTH="34%"
 356 ALIGN="center"
 357 VALIGN="top"
 358 ><A
 359 HREF="spi.html"
 360 ACCESSKEY="U"
 361 >Up</A
 362 ></TD
 363 ><TD
 364 WIDTH="33%"
 365 ALIGN="right"
 366 VALIGN="top"
 367 >SPI_palloc</TD
 368 ></TR
 369 ></TABLE
 370 ></DIV
 371 ></BODY
 372 ></HTML
 373 >