[Guile-commits] GNU Guile branch, boehm-demers-weiser-gc, updated. release_1-9-2-287-g56273de

[Ludovic Courtès]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=56273dea4bc44b798f6b661e4fca953437f512f7

The branch, boehm-demers-weiser-gc has been updated
       via  56273dea4bc44b798f6b661e4fca953437f512f7 (commit)
       via  cab6e6c0410f07b0f414215fec89842deb0a0792 (commit)
       via  0588379a2aeddc7346e9d57daa2e26f98ec7c4fd (commit)
      from  b529eb5797ca0f62e0c57fcfde8e43c5fb00b3c0 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 56273dea4bc44b798f6b661e4fca953437f512f7
Author: Ludovic Courtès <address@hidden>
Date:   Wed Sep 9 00:49:05 2009 +0200

    Update documentation of `scm_gc_malloc ()' & co.
    
    * doc/ref/api-memory.texi (Memory Blocks): Update description of
      `scm_gc_malloc ()' & co.  Add `scm_gc_malloc_pointerless ()'.

commit cab6e6c0410f07b0f414215fec89842deb0a0792
Author: Ludovic Courtès <address@hidden>
Date:   Wed Sep 9 00:04:47 2009 +0200

    Update `README'.

commit 0588379a2aeddc7346e9d57daa2e26f98ec7c4fd
Author: Ludovic Courtès <address@hidden>
Date:   Tue Sep 8 23:32:23 2009 +0200

    Fix misleading comments in `gc-benchmarks/run-benchmark.scm'.
    
    * gc-benchmarks/run-benchmark.scm (pretty-print-result): Fix comments.

-----------------------------------------------------------------------

Summary of changes:
 README                          |   13 ++++-
 doc/ref/api-memory.texi         |  103 +++++++++++++++++++++++++--------------
 gc-benchmarks/run-benchmark.scm |   10 ++--
 3 files changed, 81 insertions(+), 45 deletions(-)

diff --git a/README b/README
index bea40de..c4f24f8 100644
--- a/README
+++ b/README
@@ -33,6 +33,7 @@ Guile depends on the following external libraries.
 - libintl
 - libltdl
 - libunistring
+- libgc
 It will also use the libreadline library if it is available.  For each
 of these there is a corresponding --with-XXX-prefix option that you
 can use when invoking ./configure, if you have these libraries
@@ -68,12 +69,12 @@ Guile requires the following external packages:
   - GNU MP, at least version 4.1
 
     GNU MP is used for bignum arithmetic.  It is available from
-    http://swox.com/gmp
+    http://gmplib.org/ .
 
-  - libltdl from libtool, at least from libtool version 1.5.6
+  - libltdl from GNU Libtool, at least version 1.5.6
 
     libltdl is used for loading extensions at run-time.  It is
-    available from http://www.gnu.org/software/libtool/
+    available from http://www.gnu.org/software/libtool/ .
 
   - GNU libunistring
 
@@ -81,6 +82,12 @@ Guile requires the following external packages:
     `utf*->string' procedures.  It is available from
     http://www.gnu.org/software/libunistring/ .
 
+  - libgc, at least version 7.0
+
+    libgc (aka. the Boehm-Demers-Weiser garbage collector) is the
+    conservative garbage collector used by Guile.  It is available
+    from http://www.hpl.hp.com/personal/Hans_Boehm/gc/ .
+
 
 Special Instructions For Some Systems =====================================
 
diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi
index f492203..48cce0c 100644
--- 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.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009
 @c   Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
@@ -98,38 +98,52 @@ typically from a smob @emph{mark} function.
 @node Memory Blocks
 @subsection Memory Blocks
 
address@hidden automatically-managed memory
address@hidden GC-managed memory
address@hidden conservative garbage collection
+
 In C programs, dynamic management of memory blocks is normally done
 with the functions malloc, realloc, and free.  Guile has additional
 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 and freed with @code{scm_gc_malloc} and
address@hidden  The function @code{scm_gc_malloc} will either
-return a valid pointer or signal an error.  It will also assume that
-the new memory can be freed by a garbage collection.  The garbage
-collector uses this information to decide when to try to actually
-collect some garbage.  Memory blocks allocated with
address@hidden must be freed with @code{scm_gc_free}.
+smob) should be allocated and freed with @code{scm_gc_malloc} or
address@hidden  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
address@hidden is automatically reclaimed when the
+garbage collector no longer sees any live reference to address@hidden
+Guile up to version 1.8, memory allocated with @code{scm_gc_malloc}
address@hidden 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
+pointer to some other part of the memory, the garbage collector notices
+it and prevents it from being address@hidden Guile up to 1.8,
+memory allocated with @code{scm_gc_malloc} was @emph{not} scanned.
+Consequently, the GC had to be told explicitly about pointers to live
+objects contained in the memory block, e.g., @i{via} SMOB mark functions
+(@pxref{Smobs, @code{scm_set_smob_mark}})}.  Conversely, memory
+allocated with @code{scm_gc_malloc_pointerless} is assumed to be
+``pointer-less'' and is not scanned.
 
 For memory that is not associated with a Scheme object, you can use
 @code{scm_malloc} instead of @code{malloc}.  Like
 @code{scm_gc_malloc}, it will either return a valid pointer or signal
 an error.  However, it will not assume that the new memory block can
-be freed by a garbage collection.  The memory can be freed with
address@hidden
+be freed by a garbage collection.  The memory must be explicitly freed
+with @code{free}.
 
 There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
 in place of @code{realloc} when appropriate, and @code{scm_gc_calloc}
 and @code{scm_calloc}, to be used in place of @code{calloc} when
 appropriate.
 
-The function @code{scm_dynwind_free} can be useful when memory should
-be freed when a dynwind context, @xref{Dynamic Wind}.
-
-For really specialized needs, take at look at
address@hidden and
address@hidden
+The function @code{scm_dynwind_free} can be useful when memory should be
+freed with libc's @code{free} when leaving a dynwind context,
address@hidden Wind}.
 
 @deftypefn {C Function} {void *} scm_malloc (size_t @var{size})
 @deftypefnx {C Function} {void *} scm_calloc (size_t @var{size})
@@ -161,6 +175,36 @@ runs the GC to free up some memory when it deems it 
appropriate.
 
 
 
address@hidden {C Function} {void *} scm_gc_malloc (size_t @var{size}, const 
char address@hidden)
address@hidden {C Function} {void *} scm_gc_malloc_pointerless (size_t 
@var{size}, const char address@hidden)
address@hidden {C Function} {void *} scm_gc_realloc (void address@hidden, 
size_t @var{old_size}, size_t @var{new_size}, const char address@hidden);
address@hidden {C Function} {void *} scm_gc_calloc (size_t @var{size}, const 
char address@hidden)
+Allocate @var{size} bytes of automatically-managed memory.  The memory
+is automatically freed when no longer referenced from any live memory
+block.
+
+Memory allocated with @code{scm_gc_malloc} or @code{scm_gc_calloc} is
+scanned for pointers.  Memory allocated by
address@hidden is not scanned.
+
+The @code{scm_gc_realloc} call preserves the ``pointerlessness'' of the
+memory area pointed to by @var{mem}.  Note that you need to pass the old
+size of a reallocated memory block as well.  See below for a motivation.
address@hidden deftypefn
+
+
address@hidden {C Function} void scm_gc_free (void address@hidden, size_t 
@var{size}, const char address@hidden)
+Explicitly free the memory block pointed to by @var{mem}, which was
+previously allocated by one of the above @code{scm_gc} functions.
+
+Note that you need to explicitly pass the @var{size} parameter.  This
+is done since it should normally be easy to provide this parameter
+(for memory that is associated with GC controlled objects) and help keep
+the memory management overhead very low.  However, in Guile 2.x,
address@hidden is always ignored.
address@hidden deftypefn
+
+
 @deftypefn {C Function} void scm_gc_register_collectable_memory (void 
address@hidden, size_t @var{size}, const char address@hidden)
 Informs the GC that the memory at @var{mem} of size @var{size} can
 potentially be freed during a GC.  That is, announce that @var{mem} is
@@ -170,13 +214,12 @@ object, @var{size} bytes will be freed along with it.  
The GC will
 much bytes of memory are associated with GC controlled objects and the
 memory system figures this into its decisions when to run a GC.
 
address@hidden does not need to come from @code{scm_malloc}.  You can only
-call this function once for every memory block.
-
 The @var{what} argument is used for statistical purposes.  It should
 describe the type of object that the memory will be used for so that
 users can identify just what strange objects are eating up their
 memory.
+
+In Guile 2.x, this function has no effect.
 @end deftypefn
 
 @deftypefn {C Function} void scm_gc_unregister_collectable_memory (void 
address@hidden, size_t @var{size})
@@ -186,28 +229,11 @@ match up every call to 
@code{scm_gc_register_collectable_memory} with
 a call to @code{scm_gc_unregister_collectable_memory}.  If you don't do
 this, the GC might have a wrong impression of what is going on and run
 much less efficiently than it could.
address@hidden deftypefn
 
address@hidden {C Function} {void *} scm_gc_malloc (size_t @var{size}, const 
char address@hidden)
address@hidden {C Function} {void *} scm_gc_realloc (void address@hidden, 
size_t @var{old_size}, size_t @var{new_size}, const char address@hidden);
address@hidden {C Function} {void *} scm_gc_calloc (size_t @var{size}, const 
char address@hidden)
-Like @code{scm_malloc}, @code{scm_realloc} or @code{scm_calloc}, but
-also call @code{scm_gc_register_collectable_memory}.  Note that you
-need to pass the old size of a reallocated memory block as well.  See
-below for a motivation.
+In Guile 2.x, this function has no effect.
 @end deftypefn
 
 
address@hidden {C Function} void scm_gc_free (void address@hidden, size_t 
@var{size}, const char address@hidden)
-Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
-
-Note that you need to explicitly pass the @var{size} parameter.  This
-is done since it should normally be easy to provide this parameter
-(for memory that is associated with GC controlled objects) and this
-frees us from tracking this value in the GC itself, which will keep
-the memory management overhead very low.
address@hidden deftypefn
-
 @deftypefn {C Function} void scm_frame_free (void *mem)
 Equivalent to @code{scm_frame_unwind_handler (free, @var{mem},
 SCM_F_WIND_EXPLICITLY)}.  That is, the memory block at @var{mem} will
@@ -220,6 +246,9 @@ of malloced objects.
 @var{what} is the second argument to @code{scm_gc_malloc},
 @var{n} is the number of objects of that type currently
 allocated.
+
+This function is only available if the @code{GUILE_DEBUG_MALLOC}
+preprocessor macro was defined when Guile was compiled.
 @end deffn
 
 
diff --git a/gc-benchmarks/run-benchmark.scm b/gc-benchmarks/run-benchmark.scm
index bbe4540..7a9e67b 100755
--- a/gc-benchmarks/run-benchmark.scm
+++ b/gc-benchmarks/run-benchmark.scm
@@ -108,15 +108,15 @@ exec ${GUILE-guile} -q -l "$0"                            
      \
   (define ref-time (assoc-ref reference 'execution-time))
 
   (define (distance x1 y1 x2 y2)
-    ;; Return the distance between (X1,Y1) and (X2,Y2), using a scale such
-    ;; that REFERENCE is at (1,1).
+    ;; Return the distance between (X1,Y1) and (X2,Y2).  Y is the heap size,
+    ;; in MiB and X is the execution time in seconds.
     (let ((y1 (/ y1 (expt 2 20)))
           (y2 (/ y2 (expt 2 20))))
       (sqrt (+ (expt (- y1 y2) 2)
                (expt (- x1 x2) 2)))))
 
   (define (score time heap)
-    ;; Return a score between -1.0 and +1.0.  The score is positive if the
+    ;; Return a score lower than +1.0.  The score is positive if the
     ;; distance to the origin of (TIME,HEAP) is smaller than that of
     ;; (REF-TIME,REF-HEAP), negative otherwise.
 
@@ -124,12 +124,12 @@ exec ${GUILE-guile} -q -l "$0"                            
      \
     ;; size  |         .   worse
     ;;       |         .    [-]
     ;;       |         .
-    ;;     1 | . . . .ref. . . .
+    ;;       | . . . .ref. . . .
     ;;       |         .
     ;;       |  [+]    .
     ;;       | better  .
     ;;     0 +-------------------->
-    ;;                 1      exec. time
+    ;;                        exec. time
 
     (let ((ref-dist (distance ref-time ref-heap 0 0))
           (dist     (distance time heap 0 0)))


hooks/post-receive
-- 
GNU Guile