Concurrent dictionary: AddOrUpdate and GetOrAdd methods are not atomic (dotnet#568)

* Updated the AddOrUpdate remarks * Updated the GetOrAdd remarks * Added code style

Author: pkulikov

xml/System.Collections.Concurrent/ConcurrentDictionary`2.xml

@@ -450,12 +450,14 @@
  <param name="addValueFactory">The function used to generate a value for an absent key</param>
  <param name="updateValueFactory">The function used to generate a new value for an existing key based on the key's existing value</param>
  <summary>Uses the specified functions to add a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist, or to update a key/value pair in the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key already exists.</summary>
- <returns>The new value for the key. This will be either be the result of addValueFactory (if the key was absent) or the result of updateValueFactory (if the key was present).</returns>
+ <returns>The new value for the key. This will be either be the result of <c>addValueFactory</c> (if the key was absent) or the result of <c>updateValueFactory</c> (if the key was present).</returns>
  <remarks>
  <format type="text/markdown"><![CDATA[ 
  
 ## Remarks 
  If you call <xref:System.Collections.Concurrent.ConcurrentDictionary%602.AddOrUpdate%2A> simultaneously on different threads, `addValueFactory` may be called multiple times, but its key/value pair might not be added to the dictionary for every call. 
+
+ For modifications and write operations to the dictionary, <xref:System.Collections.Concurrent.ConcurrentDictionary%602> uses fine-grained locking to ensure thread safety. (Read operations on the dictionary are performed in a lock-free manner.) However, the `addValueFactory` and `updateValueFactory` delegates are called outside the locks to avoid the problems that can arise from executing unknown code under a lock. Therefore, <xref:System.Collections.Concurrent.ConcurrentDictionary%602.AddOrUpdate%2A> is not atomic with regards to all other operations on the <xref:System.Collections.Concurrent.ConcurrentDictionary%602> class. 
  
  ]]></format>
  </remarks>
@@ -502,7 +504,7 @@
  <param name="addValue">The value to be added for an absent key</param>
  <param name="updateValueFactory">The function used to generate a new value for an existing key based on the key's existing value</param>
  <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist, or updates a key/value pair in the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> by using the specified function if the key already exists.</summary>
- <returns>The new value for the key. This will be either be addValue (if the key was absent) or the result of updateValueFactory (if the key was present).</returns>
+ <returns>The new value for the key. This will be either be <c>addValue</c> (if the key was absent) or the result of <c>updateValueFactory</c> (if the key was present).</returns>
  <remarks>
  <format type="text/markdown"><![CDATA[ 
  
@@ -511,6 +513,9 @@
  
  [!code-csharp[System.Collections.ConcurrentColAddUpdate#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.collections.concurrentcoladdupdate/cs/program.cs#1)]
  [!code-vb[System.Collections.ConcurrentColAddUpdate#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.collections.concurrentcoladdupdate/vb/module1.vb#1)] 
+
+## Remarks 
+ For modifications and write operations to the dictionary, <xref:System.Collections.Concurrent.ConcurrentDictionary%602> uses fine-grained locking to ensure thread safety. (Read operations on the dictionary are performed in a lock-free manner.) However, the `updateValueFactory` delegate is called outside the locks to avoid the problems that can arise from executing unknown code under a lock. Therefore, <xref:System.Collections.Concurrent.ConcurrentDictionary%602.AddOrUpdate%2A> is not atomic with regards to all other operations on the <xref:System.Collections.Concurrent.ConcurrentDictionary%602> class. 
  
  ]]></format>
  </remarks>
@@ -553,14 +558,23 @@
  <Parameter Name="factoryArgument" Type="TArg" />
  </Parameters>
  <Docs>
- <typeparam name="TArg">The type of the keys in this <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /></typeparam>
+ <typeparam name="TArg">The type of an argument to pass into <c>addValueFactory</c> and <c>updateValueFactory</c>.</typeparam>
  <param name="key">The key to be added or whose value should be updated.</param>
  <param name="addValueFactory">The function used to generate a value for an absent key.</param>
  <param name="updateValueFactory">The function used to generate a new value for an existing key based on the key's existing value.</param>
  <param name="factoryArgument">An argument to pass into <c>addValueFactory</c> and <c>updateValueFactory</c>.</param>
- <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist, or updates a key/value pair in the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key already exists.</summary>
- <returns>The new value for the key. This will be either be the result of addValueFactory (if the key was absent) or the result of updateValueFactory (if the key was present).</returns>
- <remarks>To be added.</remarks>
+ <summary>Uses the specified functions and argument to add a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist, or to update a key/value pair in the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key already exists.</summary>
+ <returns>The new value for the key. This will be either be the result of <c>addValueFactory</c> (if the key was absent) or the result of <c>updateValueFactory</c> (if the key was present).</returns>
+ <remarks>
+ <format type="text/markdown"><![CDATA[ 
+ 
+## Remarks 
+ If you call <xref:System.Collections.Concurrent.ConcurrentDictionary%602.AddOrUpdate%2A> simultaneously on different threads, `addValueFactory` may be called multiple times, but its key/value pair might not be added to the dictionary for every call. 
+
+ For modifications and write operations to the dictionary, <xref:System.Collections.Concurrent.ConcurrentDictionary%602> uses fine-grained locking to ensure thread safety. (Read operations on the dictionary are performed in a lock-free manner.) However, the `addValueFactory` and `updateValueFactory` delegates are called outside the locks to avoid the problems that can arise from executing unknown code under a lock. Therefore, <xref:System.Collections.Concurrent.ConcurrentDictionary%602.AddOrUpdate%2A> is not atomic with regards to all other operations on the <xref:System.Collections.Concurrent.ConcurrentDictionary%602> class. 
+ 
+ ]]></format>
+ </remarks>
  <exception cref="T:System.ArgumentNullException">
  <paramref name="key" />, <paramref name="addValueFactory" />, or <paramref name="updateValueFactory" /> is a null reference (Nothing in Visual Basic).</exception>
  </Docs>
@@ -757,7 +771,7 @@
  <AssemblyVersion>4.0.10.0</AssemblyVersion>
  </AssemblyInfo>
  <Docs>
- <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist.</summary>
+ <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist, or returns the existing value if the key exists.</summary>
  <remarks>
  <format type="text/markdown"><![CDATA[ 
  
@@ -812,6 +826,8 @@
  <format type="text/markdown"><![CDATA[ 
  
 ## Remarks 
+ For modifications and write operations to the dictionary, <xref:System.Collections.Concurrent.ConcurrentDictionary%602> uses fine-grained locking to ensure thread safety. (Read operations on the dictionary are performed in a lock-free manner.) However, the `valueFactory` delegate is called outside the locks to avoid the problems that can arise from executing unknown code under a lock. Therefore, <xref:System.Collections.Concurrent.ConcurrentDictionary%602.GetOrAdd%2A> is not atomic with regards to all other operations on the <xref:System.Collections.Concurrent.ConcurrentDictionary%602> class. 
+
  Since 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 only one key/value pair will be added to the dictionary. 
  
  The return value depends on the presence of the key in the dictionary and whether a key/value is inserted by another thread after <xref:System.Collections.Concurrent.ConcurrentDictionary%602.GetOrAdd%2A> is called but before `valueFactory` generates a value:
@@ -864,7 +880,7 @@
  <Docs>
  <param name="key">The key of the element to add.</param>
  <param name="value">The value to be added, if the key does not already exist.</param>
- <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist.</summary>
+ <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist, or returns the existing value if the key exists.</summary>
  <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 if the key was not in the dictionary.</returns>
  <remarks>To be added.</remarks>
  <exception cref="T:System.ArgumentNullException">
@@ -905,13 +921,30 @@
  <Parameter Name="factoryArgument" Type="TArg" />
  </Parameters>
  <Docs>
- <typeparam name="TArg">The type of the keys in this <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /></typeparam>
+ <typeparam name="TArg">The type of an argument to pass into <c>valueFactory</c>.</typeparam>
  <param name="key">The key of the element to add.</param>
  <param name="valueFactory">The function used to generate a value for the key.</param>
- <param name="factoryArgument">An argument value to pass into <c>name</c>.</param>
- <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> if the key does not already exist.</summary>
- <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 <paramref name="valueFactory" /> if the key was not in the dictionary.</returns>
- <remarks>To be added.</remarks>
+ <param name="factoryArgument">An argument value to pass into <c>valueFactory</c>.</param>
+ <summary>Adds a key/value pair to the <see cref="T:System.Collections.Concurrent.ConcurrentDictionary`2" /> by using the specified function and an argument if the key does not already exist, or returns the existing value if the key exists.</summary>
+ <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 if the key was not in the dictionary.</returns>
+ <remarks>
+ <format type="text/markdown"><![CDATA[ 
+ 
+## Remarks 
+ For modifications and write operations to the dictionary, <xref:System.Collections.Concurrent.ConcurrentDictionary%602> uses fine-grained locking to ensure thread safety. (Read operations on the dictionary are performed in a lock-free manner.) However, the `valueFactory` delegate is called outside the locks to avoid the problems that can arise from executing unknown code under a lock. Therefore, <xref:System.Collections.Concurrent.ConcurrentDictionary%602.GetOrAdd%2A> is not atomic with regards to all other operations on the <xref:System.Collections.Concurrent.ConcurrentDictionary%602> class. 
+
+ Since 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 only one key/value pair will be added to the dictionary. 
+ 
+ The return value depends on the presence of the key in the dictionary and whether a key/value is inserted by another thread after <xref:System.Collections.Concurrent.ConcurrentDictionary%602.GetOrAdd%2A> is called but before `valueFactory` generates a value:
+
+ | Scenario | 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. 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. |
+ 
+ ]]></format>
+ </remarks>
  </Docs>
  </Member>
  <Member MemberName="IsEmpty">