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 |
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 |
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 |