suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix and improve docs on hash-map and hash-for-each

Browse Source 
svn: r16279
This commit is contained in:
Matthew Flatt 2009-10-08 12:06:50 +00:00
parent 33a3fccf15
commit 75dc35602c
1 changed files with 19 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
collects/scribblings/reference/hashes.scrbl
View File

@ -56,21 +56,15 @@ a table-specific semaphore as needed. Three caveats apply, however:
and future operations on the hash table may block indefinitely.} and future operations on the hash table may block indefinitely.}
@item{The @scheme[hash-map] and @scheme[hash-for-each] procedures do @item{The @scheme[hash-map] and @scheme[hash-for-each] procedures do
not use the table's semaphore. Consequently, if a hash table is not use the table's semaphore to guard the traversal as a whole.
extended with new keys by another thread while a map or for-each Changes by one thread to a hash table can affect the keys and values
traversal is in process, arbitrary key--value pairs can be dropped seen by another thread part-way through its traversal of the same
or duplicated in the traversal. Similarly, if a map or for-each hash table.}
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).}
@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 use a table's semaphore
independently for the @scheme[hash-ref] and @scheme[hash-set!] parts 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.''} ``atomic.''}
] ]
@ -284,8 +278,16 @@ Functionally removes any existing mapping for @scheme[key] in
Applies the procedure @scheme[proc] to each element in Applies the procedure @scheme[proc] to each element in
@scheme[hash] in an unspecified order, accumulating the results @scheme[hash] in an unspecified order, accumulating the results
into a list. The procedure @scheme[proc] is called each time with a into a list. The procedure @scheme[proc] is called each time with a
key and its value. See the caveat above about concurrent key and its value.
modification.
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[]} @see-also-concurrency-caveat[]}
@ -296,10 +298,10 @@ modification.
Applies @scheme[proc] to each element in @scheme[hash] (for the Applies @scheme[proc] to each element in @scheme[hash] (for the
side-effects of @scheme[proc]) in an unspecified order. The procedure 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 @scheme[proc] is called each time with a key and its value.
caveat above about concurrent modification.
@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?]) @defproc[(hash-count [hash hash?])