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
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!--
Generated from mzscheme.tex by tex2page, v 20050501
(running on MzScheme 352, unix),
(c) Dorai Sitaram,
http://www.ccs.neu.edu/~dorai/tex2page/tex2page-doc.html
-->
<head>
<title>
PLT MzScheme: Language Manual
</title>
<link rel="stylesheet" type="text/css" href="mzscheme-Z-S.css" title=default>
<meta name=robots content="noindex,follow">
</head>
<body>
<div id=content>
<div align=right class=navigation><i>[Go to <span><a href="mzscheme.html">first</a>, <a href="mzscheme-Z-H-12.html">previous</a></span><span>, <a href="mzscheme-Z-H-14.html">next</a></span> page<span>; </span><span><a href="mzscheme.html#node_toc_start">contents</a></span><span><span>; </span><a href="mzscheme-Z-H-22.html#node_index_start">index</a></span>]</i></div>
<p></p>
<a name="node_chap_13"></a>
<h1 class=chapter>
<div class=chapterheading><a href="mzscheme.html#node_toc_node_chap_13">Chapter 13</a></div><br>
<a href="mzscheme.html#node_toc_node_chap_13">Memory Management</a></h1>
<p><a name="node_idx_3156"></a></p>
<p>
</p>
<a name="node_sec_13.1"></a>
<h2><a href="mzscheme.html#node_toc_node_sec_13.1">13.1 Weak Boxes</a></h2>
<p><a name="node_idx_3158"></a></p>
<p>
<a name="node_idx_3160"></a>
A <strong>weak box</strong> is similar to a normal box (see section <a href="mzscheme-Z-H-3.html#node_sec_3.11">3.11</a>),
but when the automatic memory manager can prove that the content
value of a weak box is only reachable via weak references, the
content of the weak box is replaced
with <code class=scheme><span class=selfeval>#f</span></code>. A <strong>weak reference</strong><a name="node_idx_3162"></a> is a reference through
a weak box, through a key reference in a weak hash table
(see section <a href="mzscheme-Z-H-3.html#node_sec_3.14">3.14</a>), through a value in an ephemeron where the
value can be replaced by <code class=scheme><span class=selfeval>#f</span></code> (see section <a href="#node_sec_13.2">13.2</a>), or
through a custodian (see section <a href="mzscheme-Z-H-9.html#node_sec_9.2">9.2</a>).</p>
<p>
</p>
<ul><p>
</p>
<li><p><a name="node_idx_3164"></a><a name="node_kw_definitionmake-weak-box"></a><code class=scheme>(make-weak-box</code><tt> </tt><code class=scheme><span class=variable>v</span></code><code class=scheme>)</code> returns a new weak box that initially
contains <code class=scheme><span class=variable>v</span></code>.</p>
<p>
</p>
<li><p><a name="node_idx_3166"></a><a name="node_kw_definitionweak-box-value"></a><code class=scheme>(weak-box-value</code><tt> </tt><code class=scheme><span class=variable>weak-box</span></code><code class=scheme>)</code> returns the value contained in
<code class=scheme><span class=variable>weak-box</span></code>. If the memory manager has proven that the previous
content value of <code class=scheme><span class=variable>weak-box</span></code> was reachable only through a weak
reference, then <code class=scheme><span class=selfeval>#f</span></code> is returned.</p>
<p>
</p>
<li><p><a name="node_idx_3168"></a><a name="node_kw_definitionweak-box_Q_"></a><code class=scheme>(weak-box?</code><tt> </tt><code class=scheme><span class=variable>v</span></code><code class=scheme>)</code> returns <code class=scheme><span class=selfeval>#t</span></code> if <code class=scheme><span class=variable>v</span></code> is a weak box,
<code class=scheme><span class=selfeval>#f</span></code> otherwise.</p>
<p>
</p>
</ul><p></p>
<p>
</p>
<a name="node_sec_13.2"></a>
<h2><a href="mzscheme.html#node_toc_node_sec_13.2">13.2 Ephemerons</a></h2>
<p><a name="node_idx_3170"></a></p>
<p>
An <strong>ephemeron</strong><a name="node_idx_3172"></a> is similar to a weak box
(see section <a href="#node_sec_13.1">13.1</a>), except that
</p>
<ol><p>
</p>
<li><p>an ephemeron contains a key and a value; the value can be
extracted from the ephemeron, but the value is replaced
by <code class=scheme><span class=selfeval>#f</span></code> when the automatic memory manager can prove that
either the ephemeron or the key is reachable only through weak
references (see section <a href="#node_sec_13.1">13.1</a>); and</p>
<p>
</p>
<li><p>nothing reachable from the value in an ephemeron counts toward
the reachability of an ephemeron key (whether for the same ephemeron
or another), unless the same value is reachable through a non-weak
reference, or unless the value's ephemeron key is reachable through a
non-weak reference (see section <a href="#node_sec_13.1">13.1</a> for information on weak
references).</p>
<p>
</p>
</ol><p>
In particular, an ephemeron can be combined with a weak hash table
(see section <a href="mzscheme-Z-H-3.html#node_sec_3.14">3.14</a>) to produce a mapping where the memory
manager can reclaim key-value pairs even when the value refers to
the key. An example is shown below.</p>
<p>
</p>
<ul><p>
</p>
<li><p><a name="node_idx_3174"></a><a name="node_kw_definitionmake-ephemeron"></a><code class=scheme>(make-ephemeron</code><tt> </tt><code class=scheme><span class=variable>key-v v</span></code><code class=scheme>)</code> returns a new ephemeron whose key
is <code class=scheme><span class=variable>key-v</span></code> and whose value is initially <code class=scheme><span class=variable>v</span></code>.</p>
<p>
</p>
<li><p><a name="node_idx_3176"></a><a name="node_kw_definitionephemeron-value"></a><code class=scheme>(ephemeron-value</code><tt> </tt><code class=scheme><span class=variable>ephemeron</span></code><code class=scheme>)</code> returns the value contained
in <code class=scheme><span class=variable>ephemeron</span></code>. If the memory manager has proven that the key
for <code class=scheme><span class=variable>ephemeron</span></code> is only weakly reachable, then the result
is <code class=scheme><span class=selfeval>#f</span></code>.</p>
<p>
</p>
<li><p><a name="node_idx_3178"></a><a name="node_kw_definitionephemeron_Q_"></a><code class=scheme>(ephemeron?</code><tt> </tt><code class=scheme><span class=variable>v</span></code><code class=scheme>)</code> returns <code class=scheme><span class=selfeval>#t</span></code> if <code class=scheme><span class=variable>v</span></code> is an
ephemeron, <code class=scheme><span class=selfeval>#f</span></code> otherwise.</p>
<p>
</p>
</ul><p></p>
<p>
Example:
</p>
<div align=left><pre class=scheme><span class=comment>;; This weak map is like a weak hash table, but</span>
<span class=comment>;; without the key-in-value problem:</span>
(<span class=keyword>define</span> (<span class=variable>make-weak-map</span>)
(<code class=scheme>make-hash-table</code> <span class=keyword>'</span><span class=variable>weak</span>))
(<span class=keyword>define</span> (<span class=variable>weak-map-put!</span> <span class=variable>m</span> <span class=variable>k</span> <span class=variable>v</span>)
(<code class=scheme>hash-table-put!</code> <span class=variable>m</span> <span class=variable>k</span> (<span class=variable>make-ephemeron</span> <span class=variable>k</span> (<code class=scheme>box</code> <span class=variable>v</span>))))
(<span class=keyword>define</span> (<span class=variable>weak-map-get</span> <span class=variable>m</span> <span class=variable>k</span> <span class=variable>def-v</span>)
(<span class=keyword>let</span> ([<span class=variable>v</span> (<code class=scheme>hash-table-get</code> <span class=variable>m</span> <span class=variable>k</span> (<span class=keyword>lambda</span> () <span class=selfeval>#f</span>))])
(<span class=keyword>if</span> <span class=variable>v</span>
(<span class=keyword>let</span> ([<span class=variable>v</span> (<span class=variable>ephemeron-value</span> <span class=variable>v</span>)])
(<span class=keyword>if</span> <span class=variable>v</span>
(<code class=scheme>unbox</code> <span class=variable>v</span>)
<span class=variable>def-v</span>))
<span class=variable>def-v</span>)))
(<span class=keyword>define</span> <span class=variable>m</span> (<span class=variable>make-weak-map</span>))
(<span class=keyword>define</span> <span class=variable>k</span> (<code class=scheme>list</code> <span class=selfeval>1</span> <span class=selfeval>2</span>))
(<span class=variable>weak-map-put!</span> <span class=variable>m</span> <span class=variable>k</span> <span class=variable>k</span>)
(<span class=variable>weak-map-get</span> <span class=variable>m</span> <span class=variable>k</span> <span class=selfeval>#f</span>) <span class=comment>; => <code class=schemeresponse><span class=keyword>'</span>(<span class=selfeval>1</span> <span class=selfeval>2</span>)</code></span>
(<span class=keyword>set!</span> <span class=variable>k</span> <span class=selfeval>#f</span>)
<span class=comment> list is eventually GCed even if <code class=scheme><span class=variable>m</span></code> remains reachable</span>
</pre></div><p></p>
<p>
</p>
<a name="node_sec_13.3"></a>
<h2><a href="mzscheme.html#node_toc_node_sec_13.3">13.3 Will Executors</a></h2>
<p><a name="node_idx_3180"></a></p>
<p>
<a name="node_idx_3182"></a> <a name="node_idx_3184"></a>
<a name="node_idx_3186"></a>
A <strong>will executor</strong> manages a collection of values and
associated <strong>will procedures</strong>. The will procedure for each
value is ready to be executed when the value has been proven (by the
automatic memory manager) to be unreachable, except through weak
references (see section <a href="#node_sec_13.1">13.1</a>) or as the registrant for other will
executors. A will is useful for triggering clean-up actions on data
associated with an unreachable value, such as closing a port embedded
in an object when the object is no longer used.</p>
<p>
Calling the <code class=scheme><code class=scheme>will-execute</code></code> or <code class=scheme><code class=scheme>will-try-execute</code></code>
procedure executes a will that is ready in the specified will
executor. Wills are not executed automatically, because certain
programs need control to avoid race conditions. However, a program
can create a thread whose sole job is to execute wills for a particular
executor.</p>
<p>
</p>
<ul><p>
</p>
<li><p><a name="node_idx_3188"></a><a name="node_kw_definitionmake-will-executor"></a><code class=scheme>(make-will-executor</code><code class=scheme>)</code> returns a new will executor with no
managed values.</p>
<p>
</p>
<li><p><a name="node_idx_3190"></a><a name="node_kw_definitionwill-executor_Q_"></a><code class=scheme>(will-executor?</code><tt> </tt><code class=scheme><span class=variable>v</span></code><code class=scheme>)</code> returns <code class=scheme><span class=selfeval>#t</span></code> if <code class=scheme><span class=variable>v</span></code> is a will
executor, <code class=scheme><span class=selfeval>#f</span></code> otherwise.</p>
<p>
</p>
<li><p><a name="node_idx_3192"></a><a name="node_kw_definitionwill-register"></a><code class=scheme>(will-register</code><tt> </tt><code class=scheme><span class=variable>executor v proc</span></code><code class=scheme>)</code> registers the value <code class=scheme><span class=variable>v</span></code>
with the will procedure <code class=scheme><span class=variable>proc</span></code> in the will
executor <code class=scheme><span class=variable>executor</span></code>. When <code class=scheme><span class=variable>v</span></code> is proven unreachable, then the
procedure <code class=scheme><span class=variable>proc</span></code> is ready to be called with <code class=scheme><span class=variable>v</span></code> as its
argument via <code class=scheme><code class=scheme>will-execute</code></code> or <code class=scheme><code class=scheme>will-try-execute</code></code>.
The <code class=scheme><span class=variable>proc</span></code> argument is strongly referenced until the will
procedure is executed.</p>
<p>
</p>
<li><p><a name="node_idx_3194"></a><a name="node_kw_definitionwill-execute"></a><code class=scheme>(will-execute</code><tt> </tt><code class=scheme><span class=variable>executor</span></code><code class=scheme>)</code> invokes the will procedure for a
single ``unreachable'' value registered with the executor
<code class=scheme><span class=variable>executable</span></code>. The value(s) returned by the will procedure is the
result of the <code class=scheme><code class=scheme>will-execute</code></code> call. If no will is ready for
immediate execution, <code class=scheme><code class=scheme>will-execute</code></code> blocks until one is ready.</p>
<p>
</p>
<li><p><a name="node_idx_3196"></a><a name="node_kw_definitionwill-try-execute"></a><code class=scheme>(will-try-execute</code><tt> </tt><code class=scheme><span class=variable>executor</span></code><code class=scheme>)</code> is like <code class=scheme><code class=scheme>will-execute</code></code> if a
will is ready for immediate execution. Otherwise, <code class=scheme><span class=selfeval>#f</span></code> is
returned.</p>
<p>
</p>
</ul><p></p>
<p>
If a value is registered with multiple wills (in one or multiple
executors), the wills are readied in the reverse order of
registration. Since readying a will procedure makes the value
reachable again, the will must be executed and the value must be
proven again unreachable through only weak references before another
of the wills is readied or executed. However, wills for distinct
unreachable values are readied at the same time, regardless of
whether the values are reachable from each other.</p>
<p>
A will executor's register is held non-weakly until after the
corresponding will procedure is executed. Thus, if the content value
of a weak box (see section <a href="#node_sec_13.1">13.1</a>) is registered with a will
executor, the weak box's content is not changed to <code class=scheme><span class=selfeval>#f</span></code> until
all wills have been executed for the value and the value has been
proven again reachable through only weak references.</p>
<p>
</p>
<a name="node_sec_13.4"></a>
<h2><a href="mzscheme.html#node_toc_node_sec_13.4">13.4 Garbage Collection</a></h2>
<p><a name="node_idx_3198"></a></p>
<p>
<a name="node_idx_3200"></a><a name="node_kw_definitioncollect-garbage"></a><code class=scheme>(collect-garbage</code><code class=scheme>)</code> forces an immediate garbage collection. Since
MzScheme uses a ``conservative'' garbage collector, some effectively
unreachable data may remain uncollected (because the collector cannot
prove that it is unreachable). This procedure provides some control
over the timing of collections, but garbage will obviously be
collected even if this procedure is never called.</p>
<p>
<a name="node_idx_3202"></a><a name="node_kw_definitioncurrent-memory-use"></a><code class=scheme>(current-memory-use</code><tt> </tt>[<code class=scheme><span class=variable>custodian</span></code>]<code class=scheme>)</code> returns an estimate of the
number of bytes of memory occupied by reachable data from
<code class=scheme><span class=variable>custodian</span></code>. (The estimate is calculated <em>without</em> performing
an immediate garbage collection; performing a collection generally
decreases the number returned by <code class=scheme><code class=scheme>current-memory-use</code></code>.) If
<code class=scheme><span class=variable>custodian</span></code> is not provided, the estimate is a total reachable
from any custodians. Unless MzScheme is compiled with special support
for memory accounting, the estimate is the same (i.e., all memory)
for any individual custodian.</p>
<p>
<a name="node_idx_3204"></a><a name="node_kw_definitiondump-memory-stats"></a><code class=scheme>(dump-memory-stats</code><code class=scheme>)</code> dumps information about memory usage to the
(low-level) standard output port.</p>
<p>
</p>
<div align=right class=navigation><i>[Go to <span><a href="mzscheme.html">first</a>, <a href="mzscheme-Z-H-12.html">previous</a></span><span>, <a href="mzscheme-Z-H-14.html">next</a></span> page<span>; </span><span><a href="mzscheme.html#node_toc_start">contents</a></span><span><span>; </span><a href="mzscheme-Z-H-22.html#node_index_start">index</a></span>]</i></div>
<p></p>
</div>
</body>
</html>
|
