- "WITH-HASH-TABLE-ITERATOR ((function hash-table) &body body)
- provides a method of manually looping over the elements of a hash-table.
- FUNCTION is bound to a generator-macro that, within 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."
- (let ((n-function (gensym "WITH-HASH-TABLE-ITERATOR-")))
- `(let ((,n-function
- (let* ((table ,hash-table)
- (length (length (hash-table-next-vector table)))
- (index 1))
- (declare (type (mod #.(floor most-positive-fixnum 2)) index))
- (labels
- ((,function ()
- ;; (We grab the table again on each iteration just in
- ;; case it was rehashed by a PUTHASH.)
- (let ((kv-vector (hash-table-table table)))
- (do ()
- ((>= index length) (values nil))
- (let ((key (aref kv-vector (* 2 index)))
- (value (aref kv-vector (1+ (* 2 index)))))
- (incf index)
- (unless (and (eq key +empty-ht-slot+)
- (eq value +empty-ht-slot+))
- (return (values t key value))))))))
- #',function))))
- (macrolet ((,function () '(funcall ,n-function)))
- ,@body))))
+ "WITH-HASH-TABLE-ITERATOR ((name hash-table) &body body)
+
+Provides a method of manually looping over the elements of a hash-table. NAME
+is bound to a generator-macro that, within 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.
+
+Consequences are undefined if HASH-TABLE is mutated during execution of BODY,
+except for changing or removing elements corresponding to the current key. The
+applies to all threads, not just the curren one -- even for synchronized
+hash-tables. If the table may be mutated by another thread during iteration,
+use eg. SB-EXT:WITH-LOCKED-HASH-TABLE to protect the WITH-HASH-TABLE-ITERATOR
+for."
+ ;; This essentially duplicates MAPHASH, so any changes here should
+ ;; be reflected there as well.
+ (let ((function (make-symbol (concatenate 'string (symbol-name name) "-FUN"))))
+ `(let ((,function
+ (let* ((table ,hash-table)
+ (length (length (hash-table-next-vector table)))
+ (index 1))
+ (declare (type index/2 index))
+ (labels
+ ((,name ()
+ ;; (We grab the table again on each iteration just in
+ ;; case it was rehashed by a PUTHASH.)
+ (let ((kv-vector (hash-table-table table)))
+ (do ()
+ ((>= index length) (values nil))
+ (let ((key (aref kv-vector (* 2 index)))
+ (value (aref kv-vector (1+ (* 2 index)))))
+ (incf index)
+ (unless (or (eq key +empty-ht-slot+)
+ (eq value +empty-ht-slot+))
+ (return (values t key value))))))))
+ #',name))))
+ (macrolet ((,name () '(funcall ,function)))
+ ,@body))))
+
+(defmacro-mundanely with-locked-hash-table ((hash-table) &body body)
+ #!+sb-doc
+ "Limits concurrent accesses to HASH-TABLE for the duration of BODY.
+If HASH-TABLE is synchronized, BODY will execute with exclusive
+ownership of the table. If HASH-TABLE is not synchronized, BODY will
+execute with other WITH-LOCKED-HASH-TABLE bodies excluded -- exclusion
+of hash-table accesses not surrounded by WITH-LOCKED-HASH-TABLE is
+unspecified."
+ ;; Needless to say, this also excludes some internal bits, but
+ ;; getting there is too much detail when "unspecified" says what
+ ;; is important -- unpredictable, but harmless.
+ `(sb!thread::with-recursive-lock ((hash-table-lock ,hash-table))
+ ,@body))
+
+(defmacro-mundanely with-locked-system-table ((hash-table) &body body)
+ `(sb!thread::with-recursive-system-lock
+ ((hash-table-lock ,hash-table))
+ ,@body))