This is the mail archive of the guile@cygnus.com mailing list for the guile project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
I took mdj's recent message about weak hashes and added some texinfo cruft to fill that ugly white spot in the guile-doc that starts with 'Weak References'. The 'diff -c' patch is attached. Now, if only somebody would explain fluids the same way I'd volunteer to do the same thing to their mail ... Cheers, David
*** guile-doc/ref/scheme.texi~ Sat Oct 31 14:06:23 1998 --- guile-doc/ref/scheme.texi Sat Oct 31 13:59:56 1998 *************** *** 4000,4005 **** --- 4000,4080 ---- @node Weak References @chapter Weak References + [ This chapter is based on Mikael Djurfeldt's answer to a question by + Michael Livshin. Any mistakes are not theirs, of course. ] + + Weak references let you attach bookkeeping information to data so that + the additional information automatically disappears when the original + data is no longer in use and gets garbage collected. In a weak key hash, + the hash entry for that key disappears as soon as the key is no longer + referneced from anywhere else. For weak value hashes, the same happens + as soon as the value is no longer in use. Entries in a doubly weak hash + disappear when either the key or the value are not used anywhere else + anymore. + + Property lists offer the same kind of functionality as weak key hashes + in many situations. (@pxref{Property Lists}) + + Here's an example (a little bit strained perhaps, but one of the + examples is actually used in Guile): + + Assume that you're implementing a debugging system where you want to + associate information about filename and position of source code + expressions with the expressions themselves. + + Hashtables can be used for that, but if you use ordinary hash tables + it will be impossible for the scheme interpreter to "forget" old + source when, for example, a file is reloaded. + + To implement the mapping from source code expressions to positional + information it is necessary to use weak-key tables since we don't want + the expressions to be remembered just because they are in our table. + + To implement a mapping from source file line numbers to source code + expressions you would use a weak-value table. + + To implement a mapping from source code expressions to the procedures + they constitute a doubly-weak table has to be used. + + @section Weak key hashes + @deffn primitive make-weak-key-hash-table size + @deffnx primitive make-weak-value-hash-table size + @deffnx primitive make-doubly-weak-hash-table size + Return a weak hash table with @var{size} buckets. As with any hash + table, choosing a good size for the table requires some caution. + + You can modify weak hash tables in exactly the same way you would modify + regular hash tables. (@pxref{Hash Tables}) + @end deffn + @deffn primitive weak-key-hash-table? obj + @deffnx primitive weak-value-hash-table? obj + @deffnx primitive doubly-weak-hash-table? obj + Return @var{#t} if @var{obj} is the specified weak hash table. Note + that a doubly weak hash table is neither a weak key nor a weak value + hash table. + @end deffn + + @section Weak vectors + Weak vectors are mainly useful in Guile's implementation of weak hash + tables. + @deffn primitive make-weak-vector size [fill] + Return a weak vector with @var{size} elements. If the optional + argument @var{fill} is given, all entries in the vector will be set to + @var{fill}. The default value for @var{fill} is the empty list. + @end deffn + + @deffn primitive weak-vector . rest + @deffnx primitive list->weak-vector l + Construct a weak vector from a list: @code{weak-vector} uses the list of + its arguments while @code{list->weak-vector} uses its only argument + @var{l} (a list) to construct a weak vector the same way + @code{vector->list} would. + @end deffn + @deffn primitive weak-vector? obj + Return @var{#t} if @var{obj} is a weak vector. Note that all weak + hashes are also weak vectors. + @end deffn + @page @node Garbage Collection