From 8a072fc2d628bc85c7edadc39d50b4ff3a00d6eb Mon Sep 17 00:00:00 2001 From: Andy Wingo Date: Thu, 23 Jun 2016 22:37:23 +0200 Subject: [PATCH] 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 a2a27e43b..142eb0159 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 +@code{hashq-ref} 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