16.2 Ephemerons

An ephemeron [Hayes97] is a generalization of a weak box (see Weak Boxes). Instead of just containing one value, an ephemeron holds two values: one that is considered the value of the ephemeron and another that is the ephemeron’s key. Like the value in a weak box, the value in an ephemeron may be replaced by #f, but when the key is no longer reachable (except possibly via weak references) instead of when the value is no longer reachable.

As long as an ephemeron’s value is retained, the reference is considered a non-weak reference. References to the key via the value are treated specially, however, in that the reference does not necessarily count toward the key’s reachability. A weak box can be seen as a specialization of an ephemeron where the key and value are the same.

One particularly common use of ephemerons is to combine them with a weak hash table (see Hash Tables) to produce a mapping where the memory manager can reclaim key–value pairs even when the value refers to the key; see make-ephemeron-hash. A related use is to retain a reference to a value as long as any value for which it is an impersonator is reachable; see impersonator-ephemeron.

The retain-v argument is retained as reachable until the ephemeron’s value is extracted. It is useful, for example, when ephemeron was obtained through a weak, eq?-based mapping from key and ephemeron was created with key as the key; in that case, supplying key as retain-v ensures that ephemeron retains its value long enough for it to be extracted, even if key is otherwise unreachable.

Changed in version 7.1.0.10 of package base: Added the retain-v argument.