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

## 31.7. Weak Objects

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 `CHARACTER`s, `FIXNUM`s, and `SHORT-FLOAT`s, 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-POINTER`s, however with a more efficient in-memory representation than a plain list of `EXT:WEAK-POINTER`s 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 `k1`, `k2`, ..., as long as such a particular `kn` 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-RELATION`s 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-RELATION`s 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-MAPPING`s 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-MAPPING`s 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`.

See also Section 18.1, “Function `MAKE-HASH-TABLE`”.

Weak `HASH-TABLE`s 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-TABLE`s are also useful to implement canonicalization tables.

| These notes document CLISP version 2.45 | Last modified: 2008-05-14

Enter your search termsSubmit search form
Webclisp.cons.orgclisp.podval.orgwww.lisp.org

Prev | Up | Next
31.6. Generic streams | Home | 31.8. Finalization