/[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.4 by ttn, Tue Jan 8 08:29:00 2002 UTC revision 1.5 by mvo, Tue Feb 19 22:41:18 2002 UTC
# Line 4  Line 4 
4    
5  @menu  @menu
6  * Garbage Collection::  * Garbage Collection::
7    * Memory Blocks::
8  * Weak References::  * Weak References::
9  * Guardians::  * Guardians::
10  @end menu  @end menu
# Line 12  Line 13 
13  @node Garbage Collection  @node Garbage Collection
14  @section Garbage Collection  @section Garbage Collection
15    
 [FIXME: this is pasted in from Tom Lord's original guile.texi and should  
 be reviewed]  
   
16  @deffn {Scheme Procedure} gc  @deffn {Scheme Procedure} gc
17  @deffnx {C Function} scm_gc ()  @deffnx {C Function} scm_gc ()
18  Scans all of SCM objects and reclaims for further use those that are  Scans all of SCM objects and reclaims for further use those that are
19  no longer accessible.  no longer accessible.  You normally don't need to call this function
20    explicitely.  It is called automatically when appropriate.
21  @end deffn  @end deffn
22    
23  @deffn {Scheme Procedure} gc-stats  @deffn {Scheme Procedure} gc-stats
# Line 27  Return an association list of statistics Line 26  Return an association list of statistics
26  use of storage.  use of storage.
27  @end deffn  @end deffn
28    
29  @deffn {Scheme Procedure} object-address obj  @node Memory Blocks
30  @deffnx {C Function} scm_object_address (obj)  @section Memory Blocks
31  Return an integer that for the lifetime of @var{obj} is uniquely  
32  returned by this function for @var{obj}  In C programs, dynamic management of memory blocks is normally done
33  @end deffn  with the functions malloc, realloc, and free.  Guile has additional
34    functions for dynamic memory allocation that are integrated into the
35    garbage collector and the error reporting system.
36    
37    Memory blocks that are associated with Scheme objects (for example a
38    smob) should be allocated and freed with @code{scm_gc_malloc} and
39    @code{scm_gc_free}.  The function @code{scm_gc_malloc} will either
40    return a valid pointer or signal an error.  It will also assume that
41    the new memory can be freed by a garbage collection.  The garbage
42    collector uses this information to decide when to try to actually
43    collect some garbage.  Memory blocks allocated with
44    @code{scm_gc_malloc} must be freed with @code{scm_gc_free}.
45    
46    For memory that is not associated with a Scheme object, you can use
47    @code{scm_malloc} instead of @code{malloc}.  Like
48    @code{scm_gc_malloc}, it will either return a valid pointer or signal
49    an error.  However, it will not assume that the new memory block can
50    be freed by a garbage collection.  The memory can be freed with
51    @code{free}.
52    
53    There is also @code{scm_gc_realloc} and @code{scm_realloc}, to be used
54    in place of @code{realloc} when appropriate.
55    
56    For really specialized needs, take at look at
57    @code{scm_gc_register_collectable_memory} and
58    @code{scm_gc_unregister_collectable_memory}.
59    
60    @deftypefn {C Function} void *scm_malloc (size_t @var{size})
61    Allocate @var{size} bytes of memory and return a pointer to it.  When
62    @var{size} is 0, return @code{NULL}.  When not enough memory is
63    available, signal an error.  This function runs the GC to free up some
64    memory when it deems it appropriate.
65    
66    The memory is allocated by the libc @code{malloc} function and can be
67    freed with @code{free}.  There is no @code{scm_free} function to go
68    with @code{scm_malloc} to make it easier to pass memory back and forth
69    between different modules.
70    @end deftypefn
71    
72    @deftypefn {C Function} void *scm_realloc (void *@var{mem}, size_t @var{new_size})
73    Change the size of the memory block at @var{mem} to @var{new_size} and
74    return its new location.  When @var{new_size} is 0, this is the same
75    as calling @code{free} on @var{mem} and @code{NULL} is returned.  When
76    @var{mem} is @code{NULL}, this function behaves like @code{scm_malloc}
77    and allocates a new block of size @var{new_size}.
78    
79    When not enough memory is available, signal an error.  This function
80    runs the GC to free up some memory when it deems it appropriate.
81    @end deftypefn
82    
83    
84    @deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what})
85    Informs the GC that the memory at @var{mem} of size @var{size} can
86    potentially be freed during a GC.  That is, announce that @var{mem} is
87    part of a GC controlled object and when the GC happens to free that
88    object, @var{size} bytes will be freed along with it.  The GC will
89    @strong{not} free the memory itself, it will just know that so-and-so
90    much bytes of memory are associated with GC controlled objects and the
91    memory system figures this into its decisions when to run a GC.
92    
93    @var{mem} does not need to come from @code{scm_malloc}.  You can only
94    call this function once for every memory block.
95    
96    The @var{what} argument is used for statistical purposes.  It should
97    describe the type of object that the memory will be used for so that
98    users can identify just what strange objects are eating up their
99    memory.
100    @end deftypefn
101    
102    @deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size})
103    Informs the GC that the memory at @var{mem} of size @var{size} is no
104    longer associated with a GC controlled object.  You must take care to
105    match up every call to @code{scm_gc_register_collectable_memory} with
106    a call to @code{scm_gc_unregister_collectable_memory}.  If you don't do
107    this, the GC might have a wrong impression of what is going on and run
108    much less efficiently than it could.
109    @end deftypefn
110    
111    
112    @deftypefn {C Function} void *scm_gc_malloc (size_t @var{size}, const char *@var{what})
113    @deftypefnx {C Function} void *scm_gc_realloc (void *@var{mem}, size_t @var{old_size}, size_t @var{new_size}, const char *@var{what});
114    Like @code{scm_malloc} or @code{scm_realloc}, but also call
115    @code{scm_gc_register_collectable_memory}.  Note that you need to pass
116    the old size of a reallocated memory block as well.  See below for a
117    motivation.
118    @end deftypefn
119    
120    @deftypefn {C Function} void scm_gc_free (void *@var{mem}, size_t @var{size}, const char *@var{what})
121    Like @code{free}, but also call @code{scm_gc_unregister_collectable_memory}.
122    
123    Note that you need to explicitely pass the @var{size} parameter.  This
124    is done since it should normally be easy to provide this parameter
125    (for memory that is associated with GC controlled objects) and this
126    frees us from tracking this value in the GC itself, which will keep
127    the memory management overhead very low.
128    @end deftypefn
129    
130    
131  @node Weak References  @node Weak References
132  @section Weak References  @section Weak References
133    
134  [FIXME: This chapter is based on Mikael Djurfeldt's answer to a question  [FIXME: This chapter is based on Mikael Djurfeldt's answer to a
135  by Michael Livshin. Any mistakes are not theirs, of course. ]  question by Michael Livshin. Any mistakes are not theirs, of course. ]
136    
137  Weak references let you attach bookkeeping information to data so that  Weak references let you attach bookkeeping information to data so that
138  the additional information automatically disappears when the original  the additional information automatically disappears when the original

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

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