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