make-hash-table Function

Summary

Creates and returns a new hash table which, in addition to the standard functionality, can have a user-defined test, a user-defined hash function, and be a weak hash table.

Package

common-lisp

Signature

make-hash-table &key test size rehash-size rehash-threshold hash-function weak-kind single-thread free-function => hash-table

Arguments

Values

Description

The function make-hash-table has been extended such that test can be any suitable user-defined function, except that it must not call process-wait or similar mp package functions which suspend the current process. If test is not one of the standard test functions (eq, eql, equal and equalp), and if hash-function is not supplied, then the hash value is the same as would be used if test were equalp.

hash-function may be supplied only if test is not one of the standard test functions. It takes a hash key as its argument and returns a hash value to use for hashing.

If weak-kind is non-nil, it makes hash-table weak. Its semantics are the same as the second argument of set-hash-table-weak, that is:

(make-hash-table :weak-kind weak-kind ...other-args...)

is equivalent to:

(let ((ht (make-hash-table ...other-args...)))
  (set-hash-table-weak ht weak-kind)
  ht)

The default value of weak-kind is nil.

single-thread, if true, tells make-hash-table that the table is going to be used only in single thread contexts, and therefore does not need to be thread-safe. Single thread context means that only one thread can access the table at any point in time. That may be because the table is used only in one thread, but it can also be the case if the table is only ever accessed in the scope of a lock. Making a table with single-thread makes access to this table faster, but not thread-safe. It does not have other effects. The default value of single-thread is nil.

free-function adds a "free action" for a weak hash table. This has an effect only if make-hash-table is called with weak-kind non-nil. free-function is called after an entry is automatically removed by the garbage collector (GC). If weak-kind is nil, free-function is ignored.

free-function, if supplied, must take two arguments: key and value. When an entry is removed from a weak table hash-table because the relevant object is not pointed by any other object, the key and the value are remembered. Some time later (normally short, but not well-defined) free-function is called with key and value as its arguments.

free-function needs to be fast, to avoid delays in unexpected places. Otherwise there are no restrictions on what free-function does. In particular, it can keep the key or value alive by storing them somewhere.

When objects are removed from the table by explicit calls (remhash, clrhash, (setf gethash)), free-function is not called.

size, rehash-size and rehash-threshold are used as specified by ANSI Common Lisp.

Notes

Objects are removed from the table when the GC has identified them as free. For long-lived objects, which normally get promoted to higher generations, that may be quite a long time after the last pointer to them has gone.

free-function can also be specified in a call to set-hash-table-weak.

See also

make-hash-table in the Common Lisp HyperSpec
hash-table-weak-kind
modify-hash
set-hash-table-weak
with-hash-table-locked
11.6.8 Freeing of objects by the GC