On this page:
make-ephemeron
ephemeron-value
ephemeron?

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.

More precisely,
  • the value in an ephemeron is replaced by #f when the automatic memory manager can prove that either the ephemeron or the key is reachable only through weak references (see Weak Boxes); and

  • nothing reachable from the value in an ephemeron counts toward the reachability of an ephemeron key (whether for the same ephemeron or another), unless the same value is reachable through a non-weak reference, or unless the value’s ephemeron key is reachable through a non-weak reference (see Weak Boxes for information on weak references).

procedure

(make-ephemeron key v)  ephemeron?

  key : any/c
  v : any/c
Returns a new ephemeron whose key is key and whose value is initially v.

procedure

(ephemeron-value ephemeron [gced-v retain-v])  any/c

  ephemeron : ephemeron?
  gced-v : any/c = #f
  retain-v : any/c = #f
Returns the value contained in ephemeron. If the garbage collector has proven that the key for ephemeron is only weakly reachable, then the result is gced-v (which defaults to #f).

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.

procedure

(ephemeron? v)  boolean?

  v : any/c
Returns #t if v is an ephemeron, #f otherwise.