From 75dc35602c850a55add4a110431a6d3828168253 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 8 Oct 2009 12:06:50 +0000 Subject: [PATCH] fix and improve docs on hash-map and hash-for-each svn: r16279 --- collects/scribblings/reference/hashes.scrbl | 36 +++++++++++---------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/collects/scribblings/reference/hashes.scrbl b/collects/scribblings/reference/hashes.scrbl index f193ec32cb..56f8da31cb 100644 --- a/collects/scribblings/reference/hashes.scrbl +++ b/collects/scribblings/reference/hashes.scrbl @@ -56,21 +56,15 @@ a table-specific semaphore as needed. Three caveats apply, however: and future operations on the hash table may block indefinitely.} @item{The @scheme[hash-map] and @scheme[hash-for-each] procedures do - not use the table's semaphore. Consequently, if a hash table is - extended with new keys by another thread while a map or for-each - traversal is in process, arbitrary key--value pairs can be dropped - or duplicated in the traversal. Similarly, if a map or for-each - procedure itself extends the table, arbitrary key--value pairs can - be dropped or duplicated. However, key mappings can be deleted or - remapped by any thread with no adverse affects (i.e., the change - does not affect a traversal if the key has been seen already, - otherwise the traversal skips a deleted key or uses the remapped - key's new value).} + not use the table's semaphore to guard the traversal as a whole. + Changes by one thread to a hash table can affect the keys and values + seen by another thread part-way through its traversal of the same + hash table.} - @item{The @scheme[hash-update!] and @scheme[hash-set!] functions + @item{The @scheme[hash-update!] and @scheme[hash-ref!] functions use a table's semaphore independently for the @scheme[hash-ref] and @scheme[hash-set!] parts - of its functionality, which means that the update as a whole is not + of their functionality, which means that the update as a whole is not ``atomic.''} ] @@ -284,8 +278,16 @@ Functionally removes any existing mapping for @scheme[key] in Applies the procedure @scheme[proc] to each element in @scheme[hash] in an unspecified order, accumulating the results into a list. The procedure @scheme[proc] is called each time with a -key and its value. See the caveat above about concurrent -modification. +key and its value. + +If a hash table is extended with new keys (either through +@scheme[proc] or by another thread) while a @scheme[hash-map] or +@scheme[hash-for-each] traversal is in process, arbitrary key--value +pairs can be dropped or duplicated in the traversal. Key mappings can +be deleted or remapped (by any thread) with no adverse affects; the +change does not affect a traversal if the key has been seen already, +otherwise the traversal skips a deleted key or uses the remapped key's +new value. @see-also-concurrency-caveat[]} @@ -296,10 +298,10 @@ modification. Applies @scheme[proc] to each element in @scheme[hash] (for the side-effects of @scheme[proc]) in an unspecified order. The procedure -@scheme[proc] is called each time with a key and its value. See the -caveat above about concurrent modification. +@scheme[proc] is called each time with a key and its value. -@see-also-concurrency-caveat[]} +See @scheme[hash-map] for information about modifying @scheme[hash] +within @scheme[proc]. @see-also-concurrency-caveat[]} @defproc[(hash-count [hash hash?])