/[guile]/guile/guile-core/doc/ref/scheme-memory.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-memory.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by mvo, Tue Feb 19 22:41:18 2002 UTC revision 1.6 by mvo, Thu Feb 28 23:42:22 2002 UTC
# Line 128  the memory management overhead very low. Line 128  the memory management overhead very low.
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    

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26