From f6d89e532aff4e8aa71fb6c9527a44dcc1850be8 Mon Sep 17 00:00:00 2001 From: Alexey Radul Date: Fri, 27 May 2011 22:04:45 +0100 Subject: [PATCH] Warn that weak references are scary and hard to get right. Redirect to provided higher-level abstractions. --- doc/ref-manual/misc-datatypes.texi | 8 ++++++++ 1 file changed, 8 insertions(+) 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:: -- 2.25.1