31.7. Weak Objects

31.7. Weak Objects
Prev	Chapter 31. Platform Independent Extensions	Next

31.7.1. Weak Pointers
31.7.2. Weak Lists
31.7.3. Weak “And” Relations
31.7.4. Weak “Or” Relations
31.7.5. Weak Associations
31.7.6. Weak “And” Mappings
31.7.7. Weak “Or” Mappings
31.7.8. Weak Association Lists
31.7.9. Weak Hash Tables

Recall two terms: An object is called “"alive"” as long as it can be retrieved by the user or program, through any kind of references, starting from global and local variables. (Objects that consume no heap storage, also known as “"immediate objects"”, such as CHARACTERs, FIXNUMs, and SHORT-FLOATs, are alive indefinitely.) An object is said to be garbage-collected when its storage is reclaimed, at some moment after it becomes “"dead"”.

31.7.1. Weak Pointers

A EXT:WEAK-POINTER is an object holding a reference to a given object, without keeping the latter from being garbage-collected.

Weak Pointer API

(EXT:MAKE-WEAK-POINTER value): returns a fresh EXT:WEAK-POINTER referring to value.
(EXT:WEAK-POINTER-P object): returns true if the object is of type EXT:WEAK-POINTER.
(EXT:WEAK-POINTER-VALUE weak-pointer): returns two values: The original value and T, if the value has not yet been garbage-collected, else NIL and NIL. It is SETF-able: you can change the value that the weak pointer points to.

Weak pointers are useful for notification-based communication protocols between software modules, e.g. when a change to an object x requires a notification to an object y, as long as y is alive.

31.7.2. Weak Lists

A EXT:WEAK-LIST is an ordered collection of references to objects that does not keep the objects from being garbage-collected. It is semantically equivalent to a list of EXT:WEAK-POINTERs, however with a more efficient in-memory representation than a plain list of EXT:WEAK-POINTERs would be.

Weak List API

(EXT:MAKE-WEAK-LIST list): creates a EXT:WEAK-LIST pointing to each of the elements in the given list.
(EXT:WEAK-LIST-P object): returns true if the object is of type EXT:WEAK-LIST.
(EXT:WEAK-LIST-LIST weak-list): returns a LIST of those objects from the weak-list that are still alive.
(SETF (EXT:WEAK-LIST-LIST weak-list) list): replaces the list of objects stored by the weak-list.

Weak lists are useful for notification based communication protocols between software modules, e.g. when a change to an object x requires a notification to objects k₁, k₂, ..., as long as such a particular k_n is alive.

A EXT:WEAK-LIST with a single element is semantically equivalent to a single EXT:WEAK-POINTER.

31.7.3. Weak “And” Relations

A weak “and” relation is an ordered collection of references to objects, that does not keep the objects from being garbage-collected, and which allows access to all the objects as long as all of them are still alive. As soon as one of them is garbage-collected, the entire collection of objects becomes empty.

Weak “And” Relation API

(EXT:MAKE-WEAK-AND-RELATION list): creates a EXT:WEAK-AND-RELATION between the objects in the given list.
(EXT:WEAK-AND-RELATION-P object): returns true if the object is of type EXT:WEAK-AND-RELATION.
(EXT:WEAK-AND-RELATION-LIST weak-and-relation): returns the list of objects stored in the weak-and-relation. The returned list must not be destructively modified.

EXT:WEAK-AND-RELATIONs are useful to model relations between objects that become worthless when one of the objects dies.

A EXT:WEAK-AND-RELATION with a single element is semantically equivalent to a EXT:WEAK-POINTER.

31.7.4. Weak “Or” Relations

A weak “or” relation is an ordered collection of references to objects, that keeps all objects from being garbage-collected as long as one of them is still alive. In other words, each of them keeps all others among them from being garbage-collected. When all of them are unreferenced, the collection of objects becomes empty.

Weak “Or” Relation API

(EXT:MAKE-WEAK-OR-RELATION list): creates a EXT:WEAK-OR-RELATION between the objects in the given list.
(EXT:WEAK-OR-RELATION-P object): returns true if the object is of type EXT:WEAK-OR-RELATION.
(EXT:WEAK-OR-RELATION-LIST weak-or-relation): returns the list of objects stored in the weak-or-relation. The returned list must not be destructively modified.

EXT:WEAK-OR-RELATIONs are useful to model relations between objects that do not become worthless when one of the objects dies.

A EXT:WEAK-OR-RELATION with a single element is semantically equivalent to a EXT:WEAK-POINTER.

31.7.5. Weak Associations

A weak association is a mapping from an object called key to an object called value, that exists as long as the key is alive. In other words, as long as the key is alive, it keeps the value from being garbage-collected.

Weak Association API

(EXT:MAKE-WEAK-MAPPING key value): creates a EXT:WEAK-MAPPING.
(EXT:WEAK-MAPPING-P object): returns true if the object is of type EXT:WEAK-MAPPING.
(EXT:WEAK-MAPPING-PAIR weak-mapping): returns three values: the original key, the original value, and T, if the key has not yet been garbage-collected, else NIL, NIL, NIL.
(EXT:WEAK-MAPPING-VALUE weak-mapping): returns the value, if the key has not yet been garbage-collected, else NIL.
(SETF (EXT:WEAK-MAPPING-VALUE weak-mapping) value): replaces the value stored in the weak-mapping. It has no effect when the key has already been garbage-collected.

Weak associations are useful to supplement objects with additional information that is stored outside of the object.

31.7.6. Weak “And” Mappings

A weak “and” mapping is a mapping from a tuple of objects called keys to an object called value, that does not keep the keys from being garbage-collected and that exists as long as all keys are alive. As soon as one of the keys is garbage-collected, the entire mapping goes away.

Weak “And” Mapping API

(EXT:MAKE-WEAK-AND-MAPPING keys value): creates a EXT:WEAK-AND-MAPPING between the keys objects in the given list and the given value. The keys list must be non-empty.
(EXT:WEAK-AND-MAPPING-P object): returns true if the object is of type EXT:WEAK-AND-MAPPING.
(EXT:WEAK-AND-MAPPING-PAIR weak-and-mapping): returns three values: the list of keys, the value, and T, if none of the keys have been garbage-collected, else NIL, NIL, NIL. The returned keys list must not be destructively modified.
(EXT:WEAK-AND-MAPPING-VALUE weak-and-mapping): returns the value, if none of the keys have been garbage-collected, else NIL.
(SETF (EXT:WEAK-AND-MAPPING-VALUE weak-and-mapping) value): replaces the value stored in the weak-and-mapping. It has no effect when some key has already been garbage-collected.

EXT:WEAK-AND-MAPPINGs are useful to model properties of sets of objects that become worthless when one of the objects dies.

A EXT:WEAK-AND-MAPPING with a single key is semantically equivalent to a weak association.

31.7.7. Weak “Or” Mappings

A weak “or” mapping is a mapping from a tuple of objects called keys to an object called value, that keeps all keys and the value from being garbage-collected as long as one of the keys is still alive. In other words, each of the keys keeps all others among them and the value from being garbage-collected. When all of them are unreferenced, the entire mapping goes away.

Weak “Or” Mapping API

(EXT:MAKE-WEAK-OR-MAPPING keys value): creates a EXT:WEAK-OR-MAPPING between the keys objects in the given list and the given value. The keys list must be non-empty.
(EXT:WEAK-OR-MAPPING-P object): returns true if the object is of type EXT:WEAK-OR-MAPPING.
(EXT:WEAK-OR-MAPPING-PAIR weak-or-mapping): returns three values: the list of keys, the value, and T, if the keys have not yet been garbage-collected, else NIL, NIL, NIL. The returned keys list must not be destructively modified.
(EXT:WEAK-OR-MAPPING-VALUE weak-or-mapping): returns the value, if the keys have not yet been garbage-collected, else NIL.
(SETF (EXT:WEAK-OR-MAPPING-VALUE weak-or-mapping) value): replaces the value stored in the weak-or-mapping. It has no effect when the keys have already been garbage-collected.

EXT:WEAK-OR-MAPPINGs are useful to model properties of sets of objects that do not become worthless when one of the objects dies.

A EXT:WEAK-OR-MAPPING with a single key is semantically equivalent to a weak association.

31.7.8. Weak Association Lists

A weak association list is an ordered collection of pairs, each pair being built from an object called key and an object called value. The lifetime of each pair depends on the type of the weak association list:

:KEY: The pair exists as long as the key is not garbage-collected. As long as the key is alive, it prevents the value from being garbage-collected.
:VALUE: The pair exists as long as the value is not garbage-collected. As long as the value is alive, it prevents the key from being garbage-collected.
:KEY-AND-VALUE: The pair exists as long as the key and the value are alive.
:KEY-OR-VALUE: The pair exists as long as the key or the value are alive. As long as the key is alive, it prevents the value from being garbage-collected, and as long as the value is alive, it prevents the key from being garbage-collected.

In other words, each pair is:

:KEY: a EXT:WEAK-MAPPING from the key to the value,
:VALUE: a EXT:WEAK-MAPPING from the value to the key,
:KEY-AND-VALUE: a EXT:WEAK-AND-RELATION of the key and the value,
:KEY-OR-VALUE: a EXT:WEAK-OR-RELATION of the key and the value.

Weak Association List API

(EXT:MAKE-WEAK-ALIST :type :initial-contents): creates a EXT:WEAK-ALIST. The type argument must be one of the four aforementioned types; the default is :KEY. The initial-contents argument must be an association list.
(EXT:WEAK-ALIST-P object): returns true if the object is of type EXT:WEAK-ALIST.
(EXT:WEAK-ALIST-TYPE weak-alist): returns the type of the weak-alist.
(EXT:WEAK-ALIST-CONTENTS weak-alist): returns an association list that corresponds to the current contents of the weak-alist.
(SETF (EXT:WEAK-ALIST-CONTENTS weak-alist) contents): replaces the contents of a weak-alist. The contents argument must be an association list.
(EXT:WEAK-ALIST-ASSOC item weak-alist [:test] [:test-not] [:key]): is equivalent to (ASSOC item (EXT:WEAK-ALIST-CONTENTS weak-alist) [:test] [:test-not] [:key]).
(EXT:WEAK-ALIST-RASSOC item weak-alist [:test] [:test-not] [:key]): is equivalent to (RASSOC item (EXT:WEAK-ALIST-CONTENTS weak-alist) [:test] [:test-not] [:key]).
(EXT:WEAK-ALIST-VALUE item weak-alist [:test] [:test-not]): is equivalent to (CDR (EXT:WEAK-LIST-ASSOC item weak-alist [:test] [:test-not])).
(SETF (EXT:WEAK-ALIST-VALUE item weak-alist [:test] [:test-not]) value): replaces the value stored for item in a weak-alist. When a pair with the given item as key does not exist or has already been garbage-collected, a new pair is added to the association list.

Weak associations lists are useful to supplement objects with additional information that is stored outside of the object, when the number of such objects is known to be small.

31.7.9. Weak Hash Tables

A weak HASH-TABLE is an unordered collection of pairs, each pair being built from an object called key and an object called value. There can be only one pair with a given key in a weak HASH-TABLE. The lifetime of each pair depends on the type of the weak HASH-TABLE

:KEY: The pair exists as long as the key is not garbage-collected. As long as the key is alive, it prevents the value from being garbage-collected.
:VALUE: The pair exists as long as the value is not garbage-collected. As long as the value is alive, it prevents the key from being garbage-collected.
:KEY-AND-VALUE: The pair exists as long as the key and the value are alive.
:KEY-OR-VALUE: The pair exists as long as the key or the value are alive. As long as the key is alive, it prevents the key from being garbage-collected, and as long as the value is alive, it prevents the key from being garbage-collected.

In other words, each pair is:

:KEY: a EXT:WEAK-MAPPING from the key to the value,
:VALUE: a EXT:WEAK-MAPPING from the value to the key,
:KEY-AND-VALUE: a EXT:WEAK-AND-RELATION of the key and the value,
:KEY-OR-VALUE: a EXT:WEAK-OR-RELATION of the key and the value.

Weak HASH-TABLEs are useful to supplement objects with additional information that is stored outside of the object. This data structure scales up without performance degradation when the number of pairs is big.

Weak HASH-TABLEs are also useful to implement canonicalization tables.

Prev	Up	Next
31.6. Generic streams	Home	31.8. Finalization