- "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
+ "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