modify-hash Function

Summary

Reads and writes an entry in a hash table atomically.

Package

hcl

Signature

modify-hash hash-table key function => new-value, key

Arguments

hash-table⇩	A hash table.
key⇩	An object.
function⇩	A function designator.

Values

new-value⇩	An object.
key	An object.

Description

The function modify-hash locks the hash table hash-table. It then calls the function function with three arguments: key, the value currently associated with key in hash-table (if any), and a flag which is true if key was in the table. (This last argument is needed in case the associated value is nil).

When function returns a value new-value, modify-hash then sets new-value as the value for key in the table.

modify-hash then unlocks the hash table and returns two values, new-value and key.

The overall effect is like:

(with-hash-table-locked
 hash-table
 (multiple-value-bind (value found-p)
     (gethash key hash-table)
   (let ((new-value (funcall function
                             key value found-p)))
     (setf (gethash key hash-table) new-value)
     (values new-value key))))

but modify-hash should be more efficient.

It is guaranteed that no other thread can modify the value associated with key until modify-hash returns.

Notes

function is called with hash-table locked, so it should not do anything that may cause excessive delays, or that waits for another thread that tries to modify the table.

See also

make-hash-table
with-hash-table-locked
19.3 Atomicity and thread-safety of the LispWorks implementation
19.5 Modifying a hash table with multiprocessing