gethash-ensuring Function

Summary

A thread-safe way to get a value from a hash-table, adding a value if the key is not already present.

Package

hcl

Signature

gethash-ensuring key hash-table constructor &optional in-lock-constructor => result

Arguments

Values

Description

The function gethash-ensuring gets the value for the key key from the hash table hash-table, and if this fails constructs a new value, puts it in the table and returns it. gethash-ensuring does this in a thread-safe way, which means that all threads calling it with the same key and hash-table return the same value (as long as nothing removes it from the table).

If key is not found and constructor is non-nil, constructor is called to construct the new value. constructor is called without any lock, and can do whatever is needed. The value that constructor returns may be discarded by gethash-ensuring if, by the time it returns, there is already a matching value in hash-table (added by another thread or even inside constructor).

If in-lock-constructor is non-nil it is called with the result of constructor, or with nil if constructor is nil. in-lock-constructor is called with hash-table locked, and its return value is guaranteed to be put in the table and to be returned by gethash-ensuring. If in-lock-constructor is nil then the value that is returned by constructor, or nil, is used.

Notes

1. If constructor or in-lock-constructor are complicated, it is easier to use with-ensuring-gethash.
2. In most situations, using constructor to do all the work (which requires minimal holding of the lock) is better than using in-lock-constructor. It means that sometimes the work that constructor did is wasted, because another thread put the value in the table, but that overhead is normally less significant than the overhead of holding the lock for longer, with the associated potential deadlocks. Use in-lock-constructor only if it is essential that the result goes into the table.

See also

ensure-hash-entry
with-ensuring-gethash
19.5 Modifying a hash table with multiprocessing