From: Alexey Radul Date: Fri, 27 May 2011 21:04:45 +0000 (+0100) Subject: Warn that weak references are scary and hard to get right. X-Git-Tag: release-9.2.0~194^2 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=f6d89e532aff4e8aa71fb6c9527a44dcc1850be8;p=mit-scheme.git Warn that weak references are scary and hard to get right. Redirect to provided higher-level abstractions. --- diff --git a/doc/ref-manual/misc-datatypes.texi b/doc/ref-manual/misc-datatypes.texi index 86828158a..c9e284782 100644 --- a/doc/ref-manual/misc-datatypes.texi +++ b/doc/ref-manual/misc-datatypes.texi @@ -892,6 +892,14 @@ a weak reference (but the cdr is still strong). The heavier-weight count as holding the object in its key field strongly even if the object in its datum field does. +@strong{Warning}: Working with weak references is subtle and requires +careful analysis; most programs should avoid working with them +directly. The most common use cases for weak references ought to be +served by hash tables (@pxref{Hash Tables}), which can employ various +flavors of weak entry types, 1d tables (@pxref{1D Tables}), which hold +their keys weakly, and the association table (@pxref{The Association +Table}), which also holds its keys weakly. + @menu * Weak Pairs:: * Ephemerons::