<html lang="en">
<head>
<title>Hash Table Extensions - SBCL 1.0.31 User Manual</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="SBCL 1.0.31 User Manual">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Beyond-the-ANSI-Standard.html#Beyond-the-ANSI-Standard" title="Beyond the ANSI Standard">
<link rel="prev" href="Resolution-of-Name-Conflicts.html#Resolution-of-Name-Conflicts" title="Resolution of Name Conflicts">
<link rel="next" href="Miscellaneous-Extensions.html#Miscellaneous-Extensions" title="Miscellaneous Extensions">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This manual is part of the SBCL software system. See the `README'
file for more information.
This manual is largely derived from the manual for the CMUCL
system, which was produced at Carnegie Mellon University and later
released into the public domain. This manual is in the public
domain and is provided with absolutely no warranty. See the
`COPYING' and `CREDITS' files for more information.
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Hash-Table-Extensions"></a>
<p>
Next: <a rel="next" accesskey="n" href="Miscellaneous-Extensions.html#Miscellaneous-Extensions">Miscellaneous Extensions</a>,
Previous: <a rel="previous" accesskey="p" href="Resolution-of-Name-Conflicts.html#Resolution-of-Name-Conflicts">Resolution of Name Conflicts</a>,
Up: <a rel="up" accesskey="u" href="Beyond-the-ANSI-Standard.html#Beyond-the-ANSI-Standard">Beyond the ANSI Standard</a>
<hr>
</div>
<!-- node-name, next, previous, up -->
<h3 class="section">7.7 Hash Table Extensions</h3>
<p>Hash table extensions supported by SBCL are all controlled by keyword
arguments to <code>make-hash-table</code>.
<p><a name="Function-common_002dlisp_003amake_002dhash_002dtable"></a>
<div class="defun">
— Function: <b>cl:make-hash-table</b><var> &key test size rehash-size rehash-threshold hash-function weakness synchronized<a name="index-cl_003amake_002dhash_002dtable-253"></a></var><br>
<blockquote><p><a name="index-cl_003amake_002dhash_002dtable-254"></a>Create and return a new hash table. The keywords are as follows:
<dl>
<dt><code>:test</code><dd> Determines how keys are compared. Must a designator for one of the
standard hash table tests, or a hash table test defined using
<code>sb-ext:define-hash-table-test</code>. Additionally, when an explicit
<code>hash-function</code> is provided (see below), any two argument equivalence
predicate can be used as the <code>test</code>.
<br><dt><code>:size</code><dd> A hint as to how many elements will be put in this hash table.
<br><dt><code>:rehash-size</code><dd> Indicates how to expand the table when it fills up. If an integer, add
space for that many elements. If a floating point number (which must be
greater than 1.0), multiply the size by that amount.
<br><dt><code>:rehash-threshold</code><dd> Indicates how dense the table can become before forcing a rehash. Can be
any positive number <=1, with density approaching zero as the threshold
approaches 0. Density 1 means an average of one entry per bucket.
<br><dt><code>:hash-function</code><dd> If <code>nil</code> (the default), a hash function based on the <code>test</code> argument is used,
which then must be one of the standardized hash table test functions, or
one for which a default hash function has been defined using
<code>sb-ext:define-hash-table-test</code>. If <code>hash-function</code> is specified, the <code>test</code>
argument can be any two argument predicate consistent with it. The
<code>hash-function</code> is expected to return a non-negative fixnum hash code.
<br><dt><code>:weakness</code><dd> If <code>nil</code> (the default) it is a normal non-weak hash table. If one
of <code>:key</code>, <code>:value</code>, <code>:key-and-value</code>, <code>:key-or-value</code> it is a weak hash table.
Depending on the type of weakness the lack of references to the key and
the value may allow for removal of the entry. If <code>weakness</code> is <code>:key</code> and the
key would otherwise be garbage the entry is eligible for removal from the
hash table. Similarly, if <code>weakness</code> is <code>:value</code> the life of an entry depends
on its value's references. If <code>weakness</code> is <code>:key-and-value</code> and either the
key or the value would otherwise be garbage the entry can be removed. If
<code>weakness</code> is <code>:key-or-value</code> and both the key and the value would otherwise
be garbage the entry can be removed.
<br><dt><code>:synchronized</code><dd> If <code>nil</code> (the default), the hash-table may have multiple concurrent readers,
but results are undefined if a thread writes to the hash-table
concurrently with another reader or writer. If <code>t</code>, all concurrent accesses
are safe, but note that <code>clhs</code> 3.6 (Traversal Rules and Side Effects)
remains in force. See also: <code>sb-ext:with-locked-hash-table</code>. This keyword
argument is experimental, and may change incompatibly or be removed in the
future.
</dl>
</blockquote></div>
<p><a name="Macro-sb_002dext_003adefine_002dhash_002dtable_002dtest"></a>
<div class="defun">
— Macro: <b>sb-ext:define-hash-table-test</b><var> name hash-function<a name="index-sb_002dext_003adefine_002dhash_002dtable_002dtest-255"></a></var><br>
<blockquote><p><a name="index-sb_002dext_003adefine_002dhash_002dtable_002dtest-256"></a>Defines <code>name</code> as a new kind of hash table test for use with the <code>:test</code>
argument to <code>make-hash-table</code>, and associates a default <code>hash-function</code> with it.
<p><code>name</code> must be a symbol naming a global two argument equivalence predicate.
Afterwards both <code>'name</code> and <code>#'name</code> can be used with <code>:test</code> argument. In both
cases <code>hash-table-test</code> will return the symbol <code>name</code>.
<p><code>hash-function</code> must be a symbol naming a global hash function consistent with
the predicate, or be a <code>lambda</code> form implementing one in the current lexical
environment. The hash function must compute the same hash code for any two
objects for which <code>name</code> returns true, and subsequent calls with already hashed
objects must always return the same hash code.
<p>Note: The <code>:hash-function</code> keyword argument to <code>make-hash-table</code> can be used to
override the specified default hash-function.
<p>Attempting to define <code>name</code> in a locked package as hash-table test causes a
package lock violation.
<p>Examples:
<pre class="lisp"> ;;; 1.
</pre>
<pre class="lisp"> ;; We want to use objects of type FOO as keys (by their
;; names.) EQUALP would work, but would make the names
;; case-insensitive -- wich we don't want.
(defstruct foo (name nil :type (or null string)))
</pre>
<pre class="lisp"> ;; Define an equivalence test function and a hash function.
(defun foo-name= (f1 f2) (equal (foo-name f1) (foo-name f2)))
(defun sxhash-foo-name (f) (sxhash (foo-name f)))
</pre>
<pre class="lisp"> (define-hash-table-test foo-name= sxhash-foo-name)
</pre>
<pre class="lisp"> ;; #'foo-name would work too.
(defun make-foo-table () (make-hash-table :test 'foo-name=))
</pre>
<pre class="lisp"> ;;; 2.
</pre>
<pre class="lisp"> (defun == (x y) (= x y))
</pre>
<pre class="lisp"> (define-hash-table-test ==
(lambda (x)
;; Hash codes must be consistent with test, so
;; not (SXHASH X), since
;; (= 1 1.0) => T
;; (= (SXHASH 1) (SXHASH 1.0)) => NIL
;; Note: this doesn't deal with complex numbers or
;; bignums too large to represent as double floats.
(sxhash (coerce x 'double-float))))
</pre>
<pre class="lisp"> ;; #'== would work too
(defun make-number-table () (make-hash-table :test '==))
</pre>
</blockquote></div>
<p><a name="Macro-sb_002dext_003awith_002dlocked_002dhash_002dtable"></a>
<div class="defun">
— Macro: <b>sb-ext:with-locked-hash-table</b> (<var>hash-table</var>)<var> &body body<a name="index-sb_002dext_003awith_002dlocked_002dhash_002dtable-257"></a></var><br>
<blockquote><p><a name="index-sb_002dext_003awith_002dlocked_002dhash_002dtable-258"></a>Limits concurrent accesses to <code>hash-table</code> for the duration of <code>body</code>.
If <code>hash-table</code> is synchronized, <code>body</code> will execute with exclusive
ownership of the table. If <code>hash-table</code> is not synchronized, <code>body</code> will
execute with other <code>with-locked-hash-table</code> bodies excluded <code>--</code> exclusion
of hash-table accesses not surrounded by <code>with-locked-hash-table</code> is
unspecified.
</p></blockquote></div>
<p><a name="Function-sb_002dext_003ahash_002dtable_002dsynchronized_002dp"></a>
<div class="defun">
— Function: <b>sb-ext:hash-table-synchronized-p</b><var> instance<a name="index-sb_002dext_003ahash_002dtable_002dsynchronized_002dp-259"></a></var><br>
<blockquote><p><a name="index-sb_002dext_003ahash_002dtable_002dsynchronized_002dp-260"></a>Name of a <code>queue</code>. Can be assingned to using <code>setf</code>. Queue names
can be arbitrary printable objects, and need not be unique.
</p></blockquote></div>
<p><a name="Function-sb_002dext_003ahash_002dtable_002dweakness"></a>
<div class="defun">
— Function: <b>sb-ext:hash-table-weakness</b><var> instance<a name="index-sb_002dext_003ahash_002dtable_002dweakness-261"></a></var><br>
<blockquote><p><a name="index-sb_002dext_003ahash_002dtable_002dweakness-262"></a>Name of a <code>queue</code>. Can be assingned to using <code>setf</code>. Queue names
can be arbitrary printable objects, and need not be unique.
</p></blockquote></div>
</body></html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
723830890bac44da3d113209b14e090b
>
files
>
515
