garbage collector and the error reporting system.
Memory blocks that are associated with Scheme objects (for example a
-smob) should be allocated with @code{scm_gc_malloc} or
+foreign object) should be allocated with @code{scm_gc_malloc} or
@code{scm_gc_malloc_pointerless}. These two functions will either
return a valid pointer or signal an error. Memory blocks allocated this
-way can be freed with @code{scm_gc_free}; however, this is not strictly
-needed: memory allocated with @code{scm_gc_malloc} or
-@code{scm_gc_malloc_pointerless} is automatically reclaimed when the
-garbage collector no longer sees any live reference to it@footnote{In
-Guile up to version 1.8, memory allocated with @code{scm_gc_malloc}
-@emph{had} to be freed with @code{scm_gc_free}.}.
+way may be released explicitly; however, this is not strictly needed,
+and we recommend @emph{not} calling @code{scm_gc_free}. All memory
+allocated with @code{scm_gc_malloc} or @code{scm_gc_malloc_pointerless}
+is automatically reclaimed when the garbage collector no longer sees any
+live reference to it@footnote{In Guile up to version 1.8, memory
+allocated with @code{scm_gc_malloc} @emph{had} to be freed with
+@code{scm_gc_free}.}.
Memory allocated with @code{scm_gc_malloc} is scanned for live pointers.
This means that if @code{scm_gc_malloc}-allocated memory contains a
@deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
Explicitly free the memory block pointed to by @var{mem}, which was
-previously allocated by one of the above @code{scm_gc} functions.
+previously allocated by one of the above @code{scm_gc} functions. This
+function is almost always unnecessary, except for codebases that still
+need to compile on Guile 1.8.
Note that you need to explicitly pass the @var{size} parameter. This
is done since it should normally be easy to provide this parameter
It is especially important to call this function when large unmanaged
allocations, like images, may be freed by small Scheme allocations, like
-SMOBs.
+foreign objects.
@end deftypefn
@end deffn
-@subsubsection Upgrading from scm_must_malloc et al.
-
-Version 1.6 of Guile and earlier did not have the functions from the
-previous section. In their place, it had the functions
-@code{scm_must_malloc}, @code{scm_must_realloc} and
-@code{scm_must_free}. This section explains why we want you to stop
-using them, and how to do this.
-
-@findex scm_must_malloc
-@findex scm_must_realloc
-@findex scm_must_calloc
-@findex scm_must_free
-The functions @code{scm_must_malloc} and @code{scm_must_realloc}
-behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now,
-respectively. They would inform the GC about the newly allocated
-memory via the internal equivalent of
-@code{scm_gc_register_allocation}. However,
-@code{scm_must_free} did not unregister the memory it was about to
-free. The usual way to unregister memory was to return its size from
-a smob free function.
-
-This disconnectedness of the actual freeing of memory and reporting
-this to the GC proved to be bad in practice. It was easy to make
-mistakes and report the wrong size because allocating and freeing was
-not done with symmetric code, and because it is cumbersome to compute
-the total size of nested data structures that were freed with multiple
-calls to @code{scm_must_free}. Additionally, there was no equivalent
-to @code{scm_malloc}, and it was tempting to just use
-@code{scm_must_malloc} and never to tell the GC that the memory has
-been freed.
-
-The effect was that the internal statistics kept by the GC drifted out
-of sync with reality and could even overflow in long running programs.
-When this happened, the result was a dramatic increase in (senseless)
-GC activity which would effectively stop the program dead.
-
-@findex scm_done_malloc
-@findex scm_done_free
-The functions @code{scm_done_malloc} and @code{scm_done_free} were
-introduced to help restore balance to the force, but existing bugs did
-not magically disappear, of course.
-
-Therefore we decided to force everybody to review their code by
-deprecating the existing functions and introducing new ones in their
-place that are hopefully easier to use correctly.
-
-For every use of @code{scm_must_malloc} you need to decide whether to
-use @code{scm_malloc} or @code{scm_gc_malloc} in its place. When the
-memory block is not part of a smob or some other Scheme object whose
-lifetime is ultimately managed by the garbage collector, use
-@code{scm_malloc} and @code{free}. When it is part of a smob, use
-@code{scm_gc_malloc} and change the smob free function to use
-@code{scm_gc_free} instead of @code{scm_must_free} or @code{free} and
-make it return zero.
-
-The important thing is to always pair @code{scm_malloc} with
-@code{free}; and to always pair @code{scm_gc_malloc} with
-@code{scm_gc_free}.
-
-The same reasoning applies to @code{scm_must_realloc} and
-@code{scm_realloc} versus @code{scm_gc_realloc}.
-
-
@node Weak References
@subsection Weak References
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2012
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2012, 2014
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
#include <libguile.h>
SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
- (SCM image_smob),
+ (SCM image),
"Clear the image.")
@{
- /* C code to clear the image in @code{image_smob}... */
+ /* C code to clear the image in @code{image}... */
@}
void
The @code{SCM_DEFINE} declaration says that the C function
@code{clear_image} implements a Scheme function called
@code{clear-image}, which takes one required argument (of type
-@code{SCM} and named @code{image_smob}), no optional arguments, and no
-rest argument. The string @code{"Clear the image."} provides a short
-help text for the function, it is called a @dfn{docstring}.
+@code{SCM} and named @code{image}), no optional arguments, and no rest
+argument. The string @code{"Clear the image."} provides a short help
+text for the function, it is called a @dfn{docstring}.
@code{SCM_DEFINE} macro also defines a static array of characters
initialized to the Scheme name of the function. In this case,
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011, 2014
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
#include <libguile.h>
SCM_DEFINE (clear_image, "clear-image", 1, 0, 0,
- (SCM image_smob),
+ (SCM image),
"Clear the image.")
#define FUNC_NAME s_clear_image
@{
- /* C code to clear the image in @code{image_smob}... */
+ /* C code to clear the image in @code{image}... */
@}
#undef FUNC_NAME
The @code{SCM_DEFINE} declaration says that the C function
@code{clear_image} implements a Scheme subr called @code{clear-image},
which takes one required argument (of type @code{SCM} and named
-@code{image_smob}), no optional arguments, and no rest argument.
-@xref{Doc Snarfing}, for info on the docstring.
+@code{image}), no optional arguments, and no rest argument. @xref{Doc
+Snarfing}, for info on the docstring.
This works in concert with @code{FUNC_NAME} to also define a static
array of characters named @code{s_clear_image}, initialized to the
HCoop / bpt / guile.git / commitdiff