ConcurrentDictionary.GetOrAdd enhancement #2003
Conversation
| <returns>The value for the key. This will be either the existing value for the key if the key is already in the dictionary, or the new value for the key as returned by valueFactory if the key was not in the dictionary.</returns> | ||
| <param name="valueFactory">The function used to generate a value for the key.</param> | ||
| <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> by using the specified function if the key does not already exist, or returns the existing value if the key exists.</summary> | ||
| <returns>The value for the key. For more information, see the Remarks section.</returns> |
There was a problem hiding this comment.
We don't usually need to say this in the return section. Just add the extra info in the remarks. (and it also doesn't help if you're reading this in your IntelliSense so think about what can be helpful to the customer if all they have is IntelliSense - summary, parameters, return value)
| | -------- | ------------ | | ||
| | The key is already in the dictionary. | The existing value is returned. | | ||
| | The key is not in the dictionary. `valueFactory` generates a value. On rechecking for the key, no key is found. | The key/value is inserted into the dictionary, and the value is returned. | | ||
| | The key is not in the dictionary. `valueFactory` generates a value; but while `valueFactory` is generating the value, a different thread inserts a value for the key. After `valueFactory` executes and upon rechecking for the key, the key inserted by the other thread is found. | The value inserted by the other thread is returned. | |
There was a problem hiding this comment.
; but -> split the sentences?
| | The key is not in the dictionary. `valueFactory` generates a value. On rechecking for the key, no key is found. | The key/value is inserted into the dictionary, and the value is returned. | | ||
| | The key is not in the dictionary. `valueFactory` generates a value; but while `valueFactory` is generating the value, a different thread inserts a value for the key. After `valueFactory` executes and upon rechecking for the key, the key inserted by the other thread is found. | The value inserted by the other thread is returned. | | ||
|
|
||
| Because a key/value can be inserted by another thread while `valueFactory` is generating a value, you cannot trust that just because `valueFactory` executed its produced value will be inserted into the dictionary and returned. If you call <xref:System.Collections.Concurrent.ConcurrentDictionary%602.GetOrAdd%2A> simultaneously on different threads, `valueFactory` may be called multiple times, but its key/value pair might not be added to the dictionary for every call. |
There was a problem hiding this comment.
missing comma after executed
I feel this paragraph should be opening the remarks section.
Change the first Because to Since.
There was a problem hiding this comment.
valueFactorymay be called multiple times, but its key/value pair might not be added to the dictionary for every call
This makes it sound like it actually might be added several times. But that's not true, subsequent generated values are guaranteed to be thrown away.
I would phrase it like this:
valueFactorymay be called multiple times, but only one key/value pair will be added to the dictionary
|
LGTM. |
Fixes #1940
Initial draft errs on the side of an explicit explanation favored by @epa OP at https://github.com/dotnet/corefx/issues/13308.
cc/ @stephentoub