Merge remote-tracking branch 'origin/stable-2.0'

[bpt/guile.git] / doc / ref / api-memory.texi

diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi
index 6512650..0e37d16 100644 (file)
--- a/doc/ref/api-memory.texi
+++ b/doc/ref/api-memory.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2012, 2013
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2012, 2013, 2014
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -112,15 +112,16 @@ functions for dynamic memory allocation that are integrated into the
 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
@@ -204,7 +205,9 @@ size of a reallocated memory block as well.  See below for a motivation.
 
 @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
@@ -225,7 +228,7 @@ often (as appropriate).
 
 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
 
 
@@ -296,9 +299,9 @@ they constitute a doubly-weak table has to be used.
 @node Weak hash tables
 @subsubsection Weak hash tables
 
-@deffn {Scheme Procedure} make-weak-key-hash-table size
-@deffnx {Scheme Procedure} make-weak-value-hash-table size
-@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
+@deffn {Scheme Procedure} make-weak-key-hash-table [size]
+@deffnx {Scheme Procedure} make-weak-value-hash-table [size]
+@deffnx {Scheme Procedure} make-doubly-weak-hash-table [size]
 @deffnx {C Function} scm_make_weak_key_hash_table (size)
 @deffnx {C Function} scm_make_weak_value_hash_table (size)
 @deffnx {C Function} scm_make_doubly_weak_hash_table (size)
@@ -324,9 +327,6 @@ nor a weak value hash table.
 @node Weak vectors
 @subsubsection Weak vectors
 
-Weak vectors are mainly useful in Guile's implementation of weak hash
-tables.
-
 @deffn {Scheme Procedure} make-weak-vector size [fill]
 @deffnx {C Function} scm_make_weak_vector (size, fill)
 Return a weak vector with @var{size} elements. If the optional
@@ -346,8 +346,18 @@ the same way @code{list->vector} would.
 
 @deffn {Scheme Procedure} weak-vector? obj
 @deffnx {C Function} scm_weak_vector_p (obj)
-Return @code{#t} if @var{obj} is a weak vector. Note that all
-weak hashes are also weak vectors.
+Return @code{#t} if @var{obj} is a weak vector.
+@end deffn
+
+@deffn {Scheme Procedure} weak-vector-ref wvect k
+@deffnx {C Function} scm_weak_vector_ref (wvect, k)
+Return the @var{k}th element of the weak vector @var{wvect}, or
+@code{#f} if that element has been collected.
+@end deffn
+
+@deffn {Scheme Procedure} weak-vector-set! wvect k elt
+@deffnx {C Function} scm_weak_vector_set_x (wvect, k, elt)
+Set the @var{k}th element of the weak vector @var{wvect} to @var{elt}.
 @end deffn