Scieneer Common Lisp 1.3.9 online documentation

Hash Tables

Introduction

Hash tables are by default created with locking enabled for thread synchronisation. This may be inhibited when synchronisation is not an issue, for example when the table is used by only a single thread, or when an application synchronises access itself.

The lock needs to be acquired for synchronisation during most hash operations. For the iteration and maphash and operations, the lock is only held while internally accessing the table and so is free when executing the iteration body or calling the map function.

make-hash-table &key test size rehash-size rehash-threshold weak-p lock[Function]

Creates and returns a new hash table. The keywords are as follows:

:test
Indicates what kind of test to use. Only eq, eql, equal, and equalp are currently supported.
:size
A hint as to how many elements will be put in this hash table.
:rehash-size
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, multiple the size by that amount.
:rehash-threshold
Indicates how dense the table can become before forcing a rehash. Can be any positive number <= to 1, with density approaching zero as the threshold approaches 0. Density 1 means an average of one entry per bucket.

Extensions:

:lock
The specialized type of lock used to synchronize access to the hash table, or nil for no synchronization. The valid lock types are: :normal, :recursive, or :error-check. The default lock type is :recursive. A hash table without a lock for synchronization may be appropriate if the table is known to be used by a single thread, or if synchronization is already handled by another lock.
:weak-p
If t, do not keep entries if the key would otherwise be garbage, currently unimplemented.

with-hash-table-iterator (function hash-table) &parse-body (body decls)[Macro]

Provides a method for manually looping over the elements of a hash-table. The function is bound to a generator-macro that, withing the scope of the invocation, returns one or three values. The first value tells whether any objects remain in the hash table. when the first value is non-nil, the second and third values are the key and the value of the next object.

If the hash-table has a defined lock then it is only acquired and released by function when accessing the table, and not held for the full extent of the body.

maphash map-function hash-table[Function]

For each entry in hash-table, calls map-function on the key and value of the entry; returns nil. If the hash-table has a defined lock then it is only acquired and released when accessing the table, and is not held while calling the map-function.