[Guile-commits] 01/01: Add weak hash table documentation

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit 8a072fc2d628bc85c7edadc39d50b4ff3a00d6eb
Author: Andy Wingo <address@hidden>
Date:   Thu Jun 23 22:37:23 2016 +0200

    Add weak hash table documentation
    
    * doc/ref/api-memory.texi (Weak hash tables): Update documentation.
      Fixes #20551.
---
 doc/ref/api-memory.texi |   12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi
index a2a27e4..142eb01 100644
--- a/doc/ref/api-memory.texi
+++ b/doc/ref/api-memory.texi
@@ -309,10 +309,18 @@ 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})
+You can modify weak hash tables in exactly the same way you would modify
+regular hash tables, with the exception of the routines that act on
+handles.  Weak tables have a different implementation behind the scenes
+that doesn't have handles.  @pxref{Hash Tables}, for more on
address@hidden et al.
 @end deffn
 
+Note that in a weak-key hash table, the reference to the value is
+strong.  This means that if the value references the key, even
+indirectly, the key will never be collected, which can lead to a memory
+leak.  The reverse is true for weak value tables.
+
 @deffn {Scheme Procedure} weak-key-hash-table? obj
 @deffnx {Scheme Procedure} weak-value-hash-table? obj
 @deffnx {Scheme Procedure} doubly-weak-hash-table? obj