11.11 Weak Lists

A weak list is a special sort of list whose members are not counted as references for the purpose of garbage collection. This means that, for any object in the list, if there are no references to the object anywhere outside of the list (or other weak list or weak hash table), that object will disappear the next time a garbage collection happens. Weak lists can be useful for keeping track of things such as unobtrusive lists of another function’s buffers or markers. When that function is done with the elements, they will automatically disappear from the list.

Weak lists are used internally, for example, to manage the list holding the children of an extent—an extent that is unused but has a parent will still be reclaimed, and will automatically be removed from its parent’s list of children.

Weak lists are similar to weak hash tables (see Weak Hash Tables).

Function: weak-list-p object

This function returns non-nil if object is a weak list.

Weak lists come in one of four types:

simple

Objects in the list disappear if not referenced outside of the list.

assoc

Objects in the list disappear if they are conses and either the car or the cdr of the cons is not referenced outside of the list.

key-assoc

Objects in the list disappear if they are conses and the car is not referenced outside of the list.

value-assoc

Objects in the list disappear if they are conses and the cdr is not referenced outside of the list.

Function: make-weak-list &optional type

This function creates a new weak list of type type. type is a symbol (one of simple, assoc, key-assoc, or value-assoc, as described above) and defaults to simple.

Function: weak-list-type weak

This function returns the type of the given weak-list object.

Function: weak-list-list weak

This function returns the list contained in a weak-list object.

Function: set-weak-list-list weak new-list

This function changes the list contained in a weak-list object.