128 |
@end deftypefn |
@end deftypefn |
129 |
|
|
130 |
|
|
131 |
|
@subsection Upgrading from scm_must_malloc et al |
132 |
|
|
133 |
|
Version 1.6 of Guile and earlier did not have the functions from the |
134 |
|
previous section. In their place, it had the functions |
135 |
|
@code{scm_must_malloc}, @code{scm_must_realloc} and |
136 |
|
@code{scm_must_free}. This section explains why we want you to stop |
137 |
|
using them, and how to do this. |
138 |
|
|
139 |
|
The functions @code{scm_must_malloc} and @code{scm_must_realloc} |
140 |
|
behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now, |
141 |
|
respectively. They would inform the GC about the newly allocated |
142 |
|
memory via the internal equivalent of |
143 |
|
@code{scm_gc_register_collectable_memory}. However, |
144 |
|
@code{scm_must_free} did not unregister the memory it was about to |
145 |
|
free. The usual way to unregister memory was to return its size from |
146 |
|
a smob free function. |
147 |
|
|
148 |
|
This disconnectedness of the actual freeing of memory and reporting |
149 |
|
this to the GC proved to be bad in practice. It was easy to make |
150 |
|
mistakes and report the wrong size because allocating and freeing was |
151 |
|
not done with symmetric code, and because it is cumbersome to compute |
152 |
|
the total size of nested data structures that were freed with multiple |
153 |
|
calls to @code{scm_must_free}. Additionally, there was no equivalent |
154 |
|
to @code{scm_malloc}, and it was tempting to just use |
155 |
|
@code{scm_must_malloc} and never to tell the GC that the memory has |
156 |
|
been freed. |
157 |
|
|
158 |
|
The effect was that the internal statistics kept by the GC drifted out |
159 |
|
of sync with reality and could even overflow in long running programs. |
160 |
|
When this happened, the result was a dramatic increase in (senseless) |
161 |
|
GC activity which would effectively stop the program dead. |
162 |
|
|
163 |
|
The functions @code{scm_done_malloc} and @code{scm_done_free} were |
164 |
|
introduced to help restore balance to the force, but existing bugs did |
165 |
|
not magically disappear, of course. |
166 |
|
|
167 |
|
Therefore we decided to force everybody to review their code by |
168 |
|
deprecating the existing functions and introducing new ones in their |
169 |
|
place that are hopefully easier to use correctly. |
170 |
|
|
171 |
|
For every use of @code{scm_must_malloc} you need to decide whether to |
172 |
|
use @code{scm_malloc} or @code{scm_gc_malloc} in its place. When the |
173 |
|
memory block is not part of a smob or some other Scheme object whose |
174 |
|
lifetime is ultimately managed by the garbage collector, use |
175 |
|
@code{scm_malloc} and @code{free}. When it is part of a smob, use |
176 |
|
@code{scm_gc_malloc} and change the smob free function to use |
177 |
|
@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and |
178 |
|
make it return zero. |
179 |
|
|
180 |
|
The important thing is to always pair @code{scm_malloc} with |
181 |
|
@code{free}; and to always pair @code{scm_gc_malloc} with |
182 |
|
@code{scm_gc_free}. |
183 |
|
|
184 |
|
The same reasoning applies to @code{scm_must_realloc} and |
185 |
|
@code{scm_realloc} versus @code{scm_gc_realloc}. |
186 |
|
|
187 |
@node Weak References |
@node Weak References |
188 |
@section Weak References |
@section Weak References |
189 |
|
|