doc/ref/scheme-memory.texi

   1 @page
   2 @node Memory Management
   3 @chapter Memory Management and Garbage Collection
   4
   5 @menu
   6 * Garbage Collection::
   7 * Weak References::
   8 * Guardians::
   9 @end menu
  10
  11
  12 @node Garbage Collection
  13 @section Garbage Collection
  14
  15 [FIXME: this is pasted in from Tom Lord's original guile.texi and should
  16 be reviewed]
  17
  18 @deffn {Scheme Procedure} gc
  19 @deffnx {C Function} scm_gc ()
  20 Scans all of SCM objects and reclaims for further use those that are
  21 no longer accessible.
  22 @end deffn
  23
  24 @deffn {Scheme Procedure} gc-stats
  25 @deffnx {C Function} scm_gc_stats ()
  26 Return an association list of statistics about Guile's current
  27 use of storage.
  28 @end deffn
  29
  30 @deffn {Scheme Procedure} object-address obj
  31 @deffnx {C Function} scm_object_address (obj)
  32 Return an integer that for the lifetime of @var{obj} is uniquely
  33 returned by this function for @var{obj}
  34 @end deffn
  35
  36
  37 @node Weak References
  38 @section Weak References
  39
  40 [FIXME: This chapter is based on Mikael Djurfeldt's answer to a question
  41 by Michael Livshin. Any mistakes are not theirs, of course. ]
  42
  43 Weak references let you attach bookkeeping information to data so that
  44 the additional information automatically disappears when the original
  45 data is no longer in use and gets garbage collected. In a weak key hash,
  46 the hash entry for that key disappears as soon as the key is no longer
  47 referenced from anywhere else. For weak value hashes, the same happens
  48 as soon as the value is no longer in use. Entries in a doubly weak hash
  49 disappear when either the key or the value are not used anywhere else
  50 anymore.
  51
  52 Property lists offer the same kind of functionality as weak key hashes
  53 in many situations. (@pxref{Property Lists})
  54
  55 Here's an example (a little bit strained perhaps, but one of the
  56 examples is actually used in Guile):
  57
  58 Assume that you're implementing a debugging system where you want to
  59 associate information about filename and position of source code
  60 expressions with the expressions themselves.
  61
  62 Hashtables can be used for that, but if you use ordinary hash tables
  63 it will be impossible for the scheme interpreter to "forget" old
  64 source when, for example, a file is reloaded.
  65
  66 To implement the mapping from source code expressions to positional
  67 information it is necessary to use weak-key tables since we don't want
  68 the expressions to be remembered just because they are in our table.
  69
  70 To implement a mapping from source file line numbers to source code
  71 expressions you would use a weak-value table.
  72
  73 To implement a mapping from source code expressions to the procedures
  74 they constitute a doubly-weak table has to be used.
  75
  76 @menu
  77 * Weak key hashes::
  78 * Weak vectors::
  79 @end menu
  80
  81
  82 @node Weak key hashes
  83 @subsection Weak key hashes
  84
  85 @deffn {Scheme Procedure} make-weak-key-hash-table size
  86 @deffnx {Scheme Procedure} make-weak-value-hash-table size
  87 @deffnx {Scheme Procedure} make-doubly-weak-hash-table size
  88 @deffnx {C Function} scm_make_weak_key_hash_table (size)
  89 @deffnx {C Function} scm_make_weak_value_hash_table (size)
  90 @deffnx {C Function} scm_make_doubly_weak_hash_table (size)
  91 Return a weak hash table with @var{size} buckets. As with any
  92 hash table, choosing a good size for the table requires some
  93 caution.
  94
  95 You can modify weak hash tables in exactly the same way you
  96 would modify regular hash tables. (@pxref{Hash Tables})
  97 @end deffn
  98
  99 @deffn {Scheme Procedure} weak-key-hash-table? obj
 100 @deffnx {Scheme Procedure} weak-value-hash-table? obj
 101 @deffnx {Scheme Procedure} doubly-weak-hash-table? obj
 102 @deffnx {C Function} scm_weak_key_hash_table_p (obj)
 103 @deffnx {C Function} scm_weak_value_hash_table_p (obj)
 104 @deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
 105 Return @code{#t} if @var{obj} is the specified weak hash
 106 table. Note that a doubly weak hash table is neither a weak key
 107 nor a weak value hash table.
 108 @end deffn
 109
 110 @deffn {Scheme Procedure} make-weak-value-hash-table k
 111 @end deffn
 112
 113 @deffn {Scheme Procedure} weak-value-hash-table? x
 114 @end deffn
 115
 116 @deffn {Scheme Procedure} make-doubly-weak-hash-table k
 117 @end deffn
 118
 119 @deffn {Scheme Procedure} doubly-weak-hash-table? x
 120 @end deffn
 121
 122
 123 @node Weak vectors
 124 @subsection Weak vectors
 125
 126 Weak vectors are mainly useful in Guile's implementation of weak hash
 127 tables.
 128
 129 @deffn {Scheme Procedure} make-weak-vector size [fill]
 130 @deffnx {C Function} scm_make_weak_vector (size, fill)
 131 Return a weak vector with @var{size} elements. If the optional
 132 argument @var{fill} is given, all entries in the vector will be
 133 set to @var{fill}. The default value for @var{fill} is the
 134 empty list.
 135 @end deffn
 136
 137 @deffn {Scheme Procedure} weak-vector . l
 138 @deffnx {Scheme Procedure} list->weak-vector l
 139 @deffnx {C Function} scm_weak_vector (l)
 140 Construct a weak vector from a list: @code{weak-vector} uses
 141 the list of its arguments while @code{list->weak-vector} uses
 142 its only argument @var{l} (a list) to construct a weak vector
 143 the same way @code{list->vector} would.
 144 @end deffn
 145
 146 @deffn {Scheme Procedure} weak-vector? obj
 147 @deffnx {C Function} scm_weak_vector_p (obj)
 148 Return @code{#t} if @var{obj} is a weak vector. Note that all
 149 weak hashes are also weak vectors.
 150 @end deffn
 151
 152
 153 @node Guardians
 154 @section Guardians
 155
 156 @deffn {Scheme Procedure} make-guardian [greedy?]
 157 @deffnx {C Function} scm_make_guardian (greedy_p)
 158 Create a new guardian.
 159 A guardian protects a set of objects from garbage collection,
 160 allowing a program to apply cleanup or other actions.
 161
 162 @code{make-guardian} returns a procedure representing the guardian.
 163 Calling the guardian procedure with an argument adds the
 164 argument to the guardian's set of protected objects.
 165 Calling the guardian procedure without an argument returns
 166 one of the protected objects which are ready for garbage
 167 collection, or @code{#f} if no such object is available.
 168 Objects which are returned in this way are removed from
 169 the guardian.
 170
 171 @code{make-guardian} takes one optional argument that says whether the
 172 new guardian should be greedy or sharing.  If there is any chance
 173 that any object protected by the guardian may be resurrected,
 174 then you should make the guardian greedy (this is the default).
 175
 176 See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
 177 "Guardians in a Generation-Based Garbage Collector".
 178 ACM SIGPLAN Conference on Programming Language Design
 179 and Implementation, June 1993.
 180
 181 (the semantics are slightly different at this point, but the
 182 paper still (mostly) accurately describes the interface).
 183 @end deffn
 184
 185 @deffn {Scheme Procedure} destroy-guardian! guardian
 186 @deffnx {C Function} scm_destroy_guardian_x (guardian)
 187 Destroys @var{guardian}, by making it impossible to put any more
 188 objects in it or get any objects from it.  It also unguards any
 189 objects guarded by @var{guardian}.
 190 @end deffn
 191
 192 @deffn {Scheme Procedure} guardian-greedy? guardian
 193 @deffnx {C Function} scm_guardian_greedy_p (guardian)
 194 Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
 195 @end deffn
 196
 197 @deffn {Scheme Procedure} guardian-destroyed? guardian
 198 @deffnx {C Function} scm_guardian_destroyed_p (guardian)
 199 Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
 200 @end deffn
 201
 202
 203 @page
 204 @node Objects
 205 @chapter Objects
 206
 207 @deffn {Scheme Procedure} entity? obj
 208 @deffnx {C Function} scm_entity_p (obj)
 209 Return @code{#t} if @var{obj} is an entity.
 210 @end deffn
 211
 212 @deffn {Scheme Procedure} operator? obj
 213 @deffnx {C Function} scm_operator_p (obj)
 214 Return @code{#t} if @var{obj} is an operator.
 215 @end deffn
 216
 217 @deffn {Scheme Procedure} set-object-procedure! obj proc
 218 @deffnx {C Function} scm_set_object_procedure_x (obj, proc)
 219 Set the object procedure of @var{obj} to @var{proc}.
 220 @var{obj} must be either an entity or an operator.
 221 @end deffn
 222
 223 @deffn {Scheme Procedure} make-class-object metaclass layout
 224 @deffnx {C Function} scm_make_class_object (metaclass, layout)
 225 Create a new class object of class @var{metaclass}, with the
 226 slot layout specified by @var{layout}.
 227 @end deffn
 228
 229 @deffn {Scheme Procedure} make-subclass-object class layout
 230 @deffnx {C Function} scm_make_subclass_object (class, layout)
 231 Create a subclass object of @var{class}, with the slot layout
 232 specified by @var{layout}.
 233 @end deffn
 234
 235
 236 @c Local Variables:
 237 @c TeX-master: "guile.texi"
 238 @c End: