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