1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>40.3.Memory Management</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="spi.html" title="Chapter40.Server Programming Interface">
<link rel="prev" href="spi-spi-getnspname.html" title="SPI_getnspname">
<link rel="next" href="spi-spi-palloc.html" title="SPI_palloc">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="spi-memory"></a>40.3.Memory Management</h2></div></div></div>
<p> <span class="productname">PostgreSQL</span> allocates memory within
<em class="firstterm">memory contexts</em><a name="id738576"></a>, 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 may 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></body>
</html>
|
