Steel Bank Common Lisp

:weakness argument of make-hash-table is confusing (IMO)

Reported by Attila Lendvai on 2010-03-21
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
SBCL
Low
Unassigned

Bug Description

every time i get to create a weak hash table i always get confused by the meaning of the :weakness argument.

after i spent a bit of time thinking, i've realized that it's because the values one must give to the :weakness argument means when the entries should be _preserved_.

i suggest to rename :weakness to :preserve-if with default value T meaning that the hash table is not weak.

if that change is considered too intrusive, then please consider an alternative docstring for make-hash-table:

  :WEAKNESS
    By default, when :WEAKNESS is NIL, entries in a hashtable only get removed
    when explicitly requested by REMHASH. (Note that the name :PRESERVE-IF
    would more intuitively suggest the meaning of the values it accepts.)

    When :WEAKNESS is not NIL, it specifies how the presence of a key or value
    in the hash table preserves their hash table entries from garbage
    collection:
     - :KEY means that only those entries are guaranteed to be preserved whose
       key is otherwise a live object (meaning that there's at least one
       reference to it not considering the key slot of this hash table entry).
     - :VALUE, symmetric to :KEY, means that only those entries are guaranteed
       to be preserved whose value is otherwise a live object (meaning that
       there's at least one reference to it not considering the value slot of
       this hash table entry).
     - :KEY-AND-VALUE means that both the key and the value must be live in
       order to have a guarantee that the entry is preserved. Thus, the hash
       table does not retain neither keys nor values from garbage collection;
       if either one is eligible for collection then the entry also is.
     - :KEY-OR-VALUE means that either the key or the value can preserve the
       entry. Thus, hash table entries are eligible for collection when both
       their key and value would otherwise be collected as garbage.

Nathan Froyd (froydnj) wrote :

Renaming :WEAKNESS to :PRESERVE-IF does not seem like a beneficial change. I think the revised docstring is a (small) improvement over the existing docstring.

But the new docstring could stand a little editing: removing the :PRESERVE-IF comment is the first step. We don't need our documentation to tell users about how we thought things ought to be done.

How about something like:

"When :WEAKNESS is not NIL, garbage collection may remove entries from the hash table. The value of :WEAKNESS specifies how the presence of a key or value in the hash table preserves their entries from garbage collection. Valid values are:

:KEY means that the key of an entry must be live to guarantee that the entry is preserved.

:VALUE means that the value of an entry must be live to guarantee that the entry is preserved.

:KEY-AND-VALUE means that both the key and the value must be live to guarantee that the entry is preserved.

:KEY-OR-VALUE means that either the key or the value must be live to guarantee that the entry is preserved."

Nikodemus Siivola (nikodemus) wrote :

I'll update the docstring along the lines of Nathan's suggestion.

Changed in sbcl:
status: New → Confirmed
importance: Undecided → Low
Nikodemus Siivola (nikodemus) wrote :

In SBCL 1.0.37.52.

Changed in sbcl:
status: Confirmed → Fix Committed
Changed in sbcl:
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers