Rewrite the hash table constructors section with more weakness options.
authorAlexey Radul <axch@mit.edu>
Sun, 29 May 2011 21:37:59 +0000 (22:37 +0100)
committerTaylor R Campbell <campbell@mumble.net>
Tue, 9 Apr 2013 02:39:38 +0000 (02:39 +0000)
commita80596a56e47f3e66c4818419625a76bbdec215e
treec42a23755faef66dabb028a32de08f10d6e3021e
parentd7bb2a1b7b6665667f6b49220b7525caa8482a71
Rewrite the hash table constructors section with more weakness options.

Define and export key-ephemeral-eq and key-ephemeral-eqv tables as
replacements for the key-weak versions.

Punt descriptions of old hash table constructor procedures to the
bottom of the section and say they are for backward compatibility.

One may object to MAKE-KEY-EPHEMERAL-EQ-HASH-TABLE on the grounds that
it invites a combinatorial explosion of names:
make-key/datum-weak-eqv-hash-table
make-datum-ephemeral-string-hash-table
make-key&datum-ephemeral-equal-hash-table (!?)
and so on ad nauseam.

Where will it end?  The criterion I used to decide which names to
export and document and which names to leave alone and defer to the
general HASH-TABLE/CONSTRUCTOR mechanism was simply to update the
existing documentation.  The manual already listed
MAKE-WEAK-EQ-HASH-TABLE.  It is now named MAKE-KEY-WEAK-EQ-HASH-TABLE,
so that name is included.  But really, a key-weak table is just a
performance optimization over a key-ephemeral table, to save work when
you know the data will not hold the keys strongly.  So
MAKE-KEY-EPHEMERAL-EQ-HASH-TABLE is in; it was, in fact, the reason I
wanted Taylor to implement ephemerons in the first place.
MAKE-KEY-EPHEMERAL-EQV-HASH-TABLE is in to preserve the symmetry
between eq? and eqv? that was already present in the manual.  But the
rest of them are out, because they weren't there before.  If
datum-weak tables were so important that their constructor really must
be given a name here, then (arguably) why were they not already
implemented and documented?  The fact that MIT Scheme only supported
strong and key-weak tables for a long time suggests that those kinds
are the most common, and therefore the most deserving of slots in the
name space.
doc/ref-manual/associations.texi
src/runtime/hashtb.scm
src/runtime/runtime.pkg