9.4 Weak Dictionaries

The module WeakDictionary contains procedures operating on weak dictionaries. A weak dictionary is much like an ordinary dictionary and supports the same API. The main difference is that an entry is kept only as long as its item (i. e. the value recorded under the key) has not become garbage. If the item is only reachable through one or more weak dictionaries, the corresponding entries will automatically be dropped from all weak dictionaries at the next garbage collection.

Finalization Stream

Each weak dictionary is associated with a finalization stream. When an item X (indexed under Key) becomes garbage, the entry is automatically removed from the weak dictionary at the next garbage collection and the pair Key#X is sent on to the finalization stream (as if the weak dictionary were associated with a port and the pair was sent to it using Port.send). This means that the item, which was garbage, becomes again non-garbage when it is sent to the finalization stream. If subsequently, this last remaining reference disappears, then the item really becomes garbage since it won't be referenced even through a weak dictionary.

The finalization stream is created at the same time as the weak dictionary; both are output arguments of NewWeakDictionary. If you are not interested in the finalization stream, you can explicitly close it using WeakDictionary.close.

Module WeakDictionary can also be accessed as Dictionary.weak.

IsWeakDictionary: {WeakDictionary.is +X ?B}; tests whether X is a weak dictionary.
NewWeakDictionary: {WeakDictionary.new ?L ?Weak}; has the same arguments as Port.new. Returns a new empty weak dictionary associated with a new finalization stream L.
close: {WeakDictionary.close +Weak}; drops the finalization stream (if any). After this, any entry that becomes garbage is simply dropped instead of being sent to the finalization stream. Note that the close, put, remove, and removeAll operations cannot be used in a (subordinated) space other than where the weak dictionary has been constructed.
put: {WeakDictionary.put +Weak +LI X}; sets the item in Weak under key LI to X.
get: {WeakDictionary.get +Weak +LI X}; returns the item X of Weak under key LI.
condGet: {WeakDictionary.condGet +Weak +LI X Y}; returns the item Y of Weak under key LI, if LI is a valid key of Weak. Otherwise, returns X.
exchange: {WeakDictionary.exchange +Weak +LI OldVal NewVal}; returns the current value of Weak under key LI as item OldVal and updates the value of Weak under key LI to be NewVal.
condExchange: {WeakDictionary.condExchange +Weak +LI DefVal OldVal NewVal}; If LI is a valid key of Weak then returns the current value of Weak under key LI as item OldVal otherwise, returns DefVal as item OldVal. Sets the value of Weak under key LI to be NewVal.
keys: {WeakDictionary.keys +Weak ?LIs}; returns a list of all currently valid keys of Weak.
entries: {WeakDictionary.entries +Weak ?Ts}; returns the list of current entries of Weak. An entry is a pair LI#X, where LI is a valid key of Weak and X the corresponding item.
items: {WeakDictionary.items +Weak ?Xs}; returns the list of all items currently in Weak.
isEmpty: {WeakDictionary.isEmpty +Weak ?B}; tests whether Weak currently contains an entry.
remove: {WeakDictionary.remove +Weak +LI}; removes the item under key LI from Weak if LI is a valid key. Otherwise, does nothing.
removeAll: {WeakDictionary.removeAll +Weak}; removes all entries currently in Weak.
member: {WeakDictionary.member +Weak +LI ?B}; tests whether LI is a valid key of Weak.
toRecord: {WeakDictionary.toRecord +L +Weak ?R}; returns a record R with label L whose features and their fields correspond to the keys and their entries of Weak.