Merge pull request #59 from LeeCampbell/RecordScope

RecordScope extension method.

Author: LeeCampbell

HdrHistogram.UnitTests/Recording/RecorderTestsBase.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Threading.Tasks;
 using HdrHistogram.Utilities;
 using Xunit;
 
@@ -22,9 +23,9 @@ public void ConstructorShouldRejectInvalidParameters(
            long lowestTrackableValue, long highestTrackableValue, int numberOfSignificantValueDigits,
            string errorParamName, string errorMessage)
         {
-            var ex = Assert.Throws<ArgumentException>(() => 
-                Create(lowestTrackableValue, 
-                    highestTrackableValue, 
+            var ex = Assert.Throws<ArgumentException>(() =>
+                Create(lowestTrackableValue,
+                    highestTrackableValue,
                     numberOfSignificantValueDigits));
             Assert.Equal(errorParamName, ex.ParamName);
             Assert.StartsWith(errorMessage, ex.Message);
@@ -183,7 +184,7 @@ public void RecordValueWithExpectedInterval()
         public void RecordAction_increments_TotalCount()
         {
             var recorder = Create(DefautltLowestDiscernibleValue, DefaultHighestTrackableValue, DefaultSignificantFigures);
-            
+
             recorder.Record(() => { });
 
             var longHistogram = recorder.GetIntervalHistogram();
@@ -233,9 +234,9 @@ public void GetIntervalHistogramInto_copies_data_over_provided_Histogram()
             recorder.RecordValue(1000);
             recorder.RecordValue(10000);
             recorder.RecordValue(100000);
-            
+
             recorder.GetIntervalHistogramInto(targetHistogram);
-            
+
             Assert.Equal(3, targetHistogram.TotalCount);
             Assert.Equal(0, targetHistogram.GetCountAtValue(1));
             Assert.Equal(0, targetHistogram.GetCountAtValue(10));
@@ -259,5 +260,14 @@ public void Using_external_histogram_for_recycling_throws()
 
             recorder.GetIntervalHistogramInto(externallyCreatedHistogram);
         }
+
+        [Fact]
+        public void RecordScope_increments_TotalCount()
+        {
+            var recorder = Create(DefautltLowestDiscernibleValue, DefaultHighestTrackableValue, DefaultSignificantFigures);
+            using (recorder.RecordScope()) { }
+            var histogram = recorder.GetIntervalHistogram();
+            Assert.Equal(1, histogram.TotalCount);
+        }
     }
 }

HdrHistogram/HistogramExtensions.cs

@@ -206,5 +206,49 @@ public static void Record(this IRecorder recorder, Action action)
             var elapsed = Stopwatch.GetTimestamp() - start;
             recorder.RecordValue(elapsed);
         }
+
+        /// <summary>
+        /// Records the elapsed time till the returned token is disposed.
+        /// This can be useful to testing large blocks of code, or wrapping around and <c>await</c> clause.
+        /// </summary>
+        /// <param name="recorder">The <see cref="IRecorder"/> instance to record the latency in.</param>
+        /// <returns>Returns a token to be disposed once the scope </returns>
+        /// <remarks>
+        /// This can be helpful for recording a scope of work.
+        /// It also has the benefit of allowing a simple way to record an awaitable method.
+        /// <example>
+        /// This example shows how an awaitable method can be cleanly instrumented using C# using scope.
+        /// <code>
+        /// using(recorder.RecordScope())
+        /// {
+        ///     await SomeExpensiveCall();
+        /// }
+        /// </code>
+        /// </example>
+        /// It should be noted that this method returns a token and as such allocates an object.
+        /// This should taken into consideration, specifically the cost of the allocation and GC would affect the program.
+        /// </remarks>
+        public static IDisposable RecordScope(this IRecorder recorder)
+        {
+            return new Timer(recorder);
+        }
+
+        private sealed class Timer : IDisposable
+        {
+            private readonly IRecorder _recorder;
+            private readonly long _start;
+
+            public Timer(IRecorder recorder)
+            {
+                _recorder = recorder;
+                _start = Stopwatch.GetTimestamp();
+            }
+
+            public void Dispose()
+            {
+                var elapsed = Stopwatch.GetTimestamp() - _start;
+                _recorder.RecordValue(elapsed);
+            }
+        }
     }
 }