docs

Author: Alex Peck

BitFaster.Caching/Atomic/AtomicFactory.cs

@@ -1,15 +1,14 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;
-using System.Diagnostics.CodeAnalysis;
 using System.Runtime.ExceptionServices;
 using System.Threading;
 
 namespace BitFaster.Caching.Atomic
 {
     /// <summary>
-    /// A class that provides simple, lightweight exactly once initialization for values
-    /// stored in a cache.
+    /// A class that provides simple, lightweight exactly once initialization for values stored
+    /// in a cache. Exceptions are propogated to the caller.
     /// </summary>
     /// <typeparam name="K">The type of the key.</typeparam>
     /// <typeparam name="V">The type of the value.</typeparam>
@@ -94,6 +93,18 @@ public V ValueIfCreated
             }
         }
 
+        /// <summary>
+        /// Note the failure case works like this:
+        /// 1. Thread A enters AtomicFactory.CreateValue then Initializer.CreateValue and holds the lock.
+        /// 2. Thread B enters AtomicFactory.CreateValue then Initializer.CreateValue and queues on the lock.
+        /// 3. Thread A calls value factory, and after 1 second throws an exception. The exception is 
+        /// captured in exceptionDispatch, lock is released, and an exeption is thrown.
+        /// 4. AtomicFactory.CreateValue catches the exception and creates a fresh initializer.
+        /// 5. Thread B enters the lock, finds exceptionDispatch is populated and immediately throws.
+        /// 6. Thread C can now start from a clean state.
+        /// This mitigates lock convoys where many queued threads will fail slowly one by one, introducing delays
+        /// and multiplying the number of calls to the failing resource.
+        /// </summary>
         private V CreateValue<TFactory>(K key, TFactory valueFactory) where TFactory : struct, IValueFactory<K, V>
         {
             var init = Volatile.Read(ref initializer);