Unit test Writer.Append(). Clean up

LeeCampbell · LeeCampbell · commit 733469246b7e · 2016-06-16T20:14:47.000+08:00
diff --git a/src/HdrHistogram.Examples/RecorderExample.cs b/src/HdrHistogram.Examples/RecorderExample.cs
@@ -14,10 +14,10 @@ namespace HdrHistogram.Examples
     /// </summary>
     static class RecorderExample
     {
-        private static readonly Recorder Recorder = new Recorder(1, TimeSpan.TicksPerHour, 3, (id, low, high, sf) => new LongHistogram(id, low, high, sf));
+        private static readonly Recorder Recorder = new Recorder(1, TimeStamp.Hours(1), 3, (id, low, high, sf) => new LongHistogram(id, low, high, sf));
         private static readonly Lazy<AddressFamily> AddressFamily = new Lazy<AddressFamily>(() => GetAddressFamily("google.com"));
         private static readonly TimeSpan RunPeriod = TimeSpan.FromSeconds(10);
-        private static readonly LongHistogram AccumulatingHistogram = new LongHistogram(TimeSpan.TicksPerHour, 3);
+        private static readonly LongHistogram AccumulatingHistogram = new LongHistogram(TimeStamp.Hours(1), 3);
         private const string LogPath = "DatagramSocket.histogram.log";        
         private static HistogramLogWriter _logWriter;
         private static FileStream _outputStream;
diff --git a/src/HdrHistogram.Examples/SimpleHistogramExample.cs b/src/HdrHistogram.Examples/SimpleHistogramExample.cs
@@ -49,7 +49,7 @@ private static void RecordMeasurements()
         }
 
         /// <summary>
-        /// Write to the console the Memory footprint of the histogram instance and
+        /// Write to the console the memory footprint of the histogram instance and
         /// the percentile distribution of all the recorded values.
         /// </summary>
         private static void OutputMeasurements()
diff --git a/src/HdrHistogram.UnitTests/Persistence/HistogramLogReaderWriterTestBase.cs b/src/HdrHistogram.UnitTests/Persistence/HistogramLogReaderWriterTestBase.cs
@@ -78,6 +78,32 @@ public void CanRoundTripSingleHistogramsWithSparseValues()
             HistogramAssert.AreValueEqual(histogram, actualHistograms.Single());
         }
 
+        [Test]
+        public void CanAppendHistogram()
+        {
+            var histogram1 = Create(highestTrackableValue: long.MaxValue - 1, numberOfSignificantValueDigits: 3);
+            histogram1.RecordValue(1);
+            histogram1.RecordValue((long.MaxValue / 2) + 1);
+            histogram1.SetTimes();
+            var histogram2 = Create(highestTrackableValue: long.MaxValue - 1, numberOfSignificantValueDigits: 3);
+            histogram2.RecordValue(2);
+            histogram2.SetTimes();
+
+            byte[] data;
+            using (var writerStream = new MemoryStream())
+            using(var log = new HistogramLogWriter(writerStream))
+            {
+                log.Append(histogram1);
+                log.Append(histogram2);
+                data = writerStream.ToArray();
+            }
+            var actualHistograms = data.ReadHistograms();
+
+            Assert.AreEqual(2, actualHistograms.Length);
+            HistogramAssert.AreValueEqual(histogram1, actualHistograms.First());
+            HistogramAssert.AreValueEqual(histogram2, actualHistograms.Skip(1).First());
+        }
+        
         [TestCase("jHiccup-2.0.7S.logV2.hlog")]
         public void CanReadv2Logs(string logPath)
         {
diff --git a/src/HdrHistogram/HistogramExtensions.cs b/src/HdrHistogram/HistogramExtensions.cs
@@ -169,7 +169,7 @@ public static void OutputPercentileDistribution(this HistogramBase histogram,
         /// conversion at time of recording. 
         /// Instead conversion (scaling) can be done at time of output to microseconds, milliseconds,
         /// seconds or other appropriate unit.
-        /// These units are sometimes refered to as ticks, but should not not to be confused with 
+        /// These units are sometimes referred to as ticks, but should not not to be confused with 
         /// ticks used in <seealso cref="DateTime"/> or <seealso cref="TimeSpan"/>.
         /// </para>
         /// <para>
diff --git a/src/HdrHistogram/HistogramLogWriter.cs b/src/HdrHistogram/HistogramLogWriter.cs
@@ -13,6 +13,7 @@ public sealed class HistogramLogWriter : IDisposable
         private const string HistogramLogFormatVersion = "1.2";
 
         private readonly TextWriter _log;
+        private bool _hasHeaderWritten = false;
 
         /// <summary>
         /// Writes the provided histograms to the underlying <see cref="Stream"/> with a given overall start time.
@@ -27,12 +28,7 @@ public static void Write(Stream outputStream, DateTime startTime, params Histogr
                 writer.Write(startTime, histograms);
             }
         }
-
-        public void Append(HistogramBase histogram)
-        {
-            WriteHistogram(histogram);
-        }
-
+        
         /// <summary>
         /// Creates a <see cref="HistogramLogWriter"/> that writes to an underlying <see cref="Stream"/>.
         /// </summary>
@@ -58,12 +54,29 @@ public void Write(DateTime startTime, params HistogramBase[] histograms)
             WriteLogFormatVersion();
             WriteStartTime(startTime);
             WriteLegend();
+            _hasHeaderWritten = true;
             foreach (var histogram in histograms)
             {
                 WriteHistogram(histogram);
             }
         }
 
+        /// <summary>
+        /// Appends a Histogram to the log. 
+        /// </summary>
+        /// <param name="histogram">The histogram to write to the log.</param>
+        public void Append(HistogramBase histogram)
+        {
+            if (!_hasHeaderWritten)
+            {
+                Write(histogram.StartTimeStamp.ToDateFromMillisecondsSinceEpoch(), histogram);
+            }
+            else
+            {
+                WriteHistogram(histogram);
+            }
+        }
+
         /// <summary>
         /// Output a log format version to the log.
         /// </summary>
diff --git a/src/HdrHistogram/IntHistogram.cs b/src/HdrHistogram/IntHistogram.cs
@@ -66,6 +66,28 @@ public IntHistogram(long lowestTrackableValue, long highestTrackableValue, int n
         {
             _counts = new int[CountsArrayLength];
         }
+
+        /// <summary>
+        /// Construct a <see cref="IntHistogram"/> given the lowest and highest values to be tracked and a number of significant decimal digits.
+        /// </summary>
+        /// <param name="instanceId">An identifier for this instance.</param>
+        /// <param name="lowestTrackableValue">The lowest value that can be tracked (distinguished from 0) by the histogram.
+        /// Must be a positive integer that is &gt;= 1.
+        /// May be internally rounded down to nearest power of 2.
+        /// </param>
+        /// <param name="highestTrackableValue">The highest value to be tracked by the histogram.
+        /// Must be a positive integer that is &gt;= (2 * lowestTrackableValue).
+        /// </param>
+        /// <param name="numberOfSignificantValueDigits">
+        /// The number of significant decimal digits to which the histogram will maintain value resolution and separation. 
+        /// Must be a non-negative integer between 0 and 5.
+        /// </param>
+        /// <remarks>
+        /// Providing a lowestTrackableValue is useful in situations where the units used for the histogram's values are much 
+        /// smaller that the minimal accuracy required.
+        /// For example when tracking time values stated in ticks (100 nanoseconds), where the minimal accuracy required is a
+        /// microsecond, the proper value for lowestTrackableValue would be 10.
+        /// </remarks>
         public IntHistogram(long instanceId, long lowestTrackableValue, long highestTrackableValue,
                          int numberOfSignificantValueDigits)
             : base(instanceId, lowestTrackableValue, highestTrackableValue, numberOfSignificantValueDigits)
diff --git a/src/HdrHistogram/LongHistogram.cs b/src/HdrHistogram/LongHistogram.cs
@@ -68,6 +68,28 @@ public LongHistogram(long lowestTrackableValue, long highestTrackableValue,
         {
             _counts = new long[CountsArrayLength];
         }
+
+        /// <summary>
+        /// Construct a <see cref="LongHistogram"/> given the lowest and highest values to be tracked and a number of significant decimal digits.
+        /// </summary>
+        /// <param name="instanceId">An identifier for this instance.</param>
+        /// <param name="lowestTrackableValue">The lowest value that can be tracked (distinguished from 0) by the histogram.
+        /// Must be a positive integer that is &gt;= 1.
+        /// May be internally rounded down to nearest power of 2.
+        /// </param>
+        /// <param name="highestTrackableValue">The highest value to be tracked by the histogram.
+        /// Must be a positive integer that is &gt;= (2 * lowestTrackableValue).
+        /// </param>
+        /// <param name="numberOfSignificantValueDigits">
+        /// The number of significant decimal digits to which the histogram will maintain value resolution and separation. 
+        /// Must be a non-negative integer between 0 and 5.
+        /// </param>
+        /// <remarks>
+        /// Providing a lowestTrackableValue is useful in situations where the units used for the histogram's values are much 
+        /// smaller that the minimal accuracy required.
+        /// For example when tracking time values stated in ticks (100 nanoseconds), where the minimal accuracy required is a
+        /// microsecond, the proper value for lowestTrackableValue would be 10.
+        /// </remarks>
         public LongHistogram(long instanceId, long lowestTrackableValue, long highestTrackableValue,
                          int numberOfSignificantValueDigits)
             : base(instanceId, lowestTrackableValue, highestTrackableValue, numberOfSignificantValueDigits)
diff --git a/src/HdrHistogram/ShortHistogram.cs b/src/HdrHistogram/ShortHistogram.cs
@@ -68,6 +68,28 @@ public ShortHistogram(long lowestTrackableValue, long highestTrackableValue, int
         {
             _counts = new short[CountsArrayLength];
         }
+
+        /// <summary>
+        /// Construct a <see cref="ShortHistogram"/> given the lowest and highest values to be tracked and a number of significant decimal digits.
+        /// </summary>
+        /// <param name="instanceId">An identifier for this instance.</param>
+        /// <param name="lowestTrackableValue">The lowest value that can be tracked (distinguished from 0) by the histogram.
+        /// Must be a positive integer that is &gt;= 1.
+        /// May be internally rounded down to nearest power of 2.
+        /// </param>
+        /// <param name="highestTrackableValue">The highest value to be tracked by the histogram.
+        /// Must be a positive integer that is &gt;= (2 * lowestTrackableValue).
+        /// </param>
+        /// <param name="numberOfSignificantValueDigits">
+        /// The number of significant decimal digits to which the histogram will maintain value resolution and separation. 
+        /// Must be a non-negative integer between 0 and 5.
+        /// </param>
+        /// <remarks>
+        /// Providing a lowestTrackableValue is useful in situations where the units used for the histogram's values are much 
+        /// smaller that the minimal accuracy required.
+        /// For example when tracking time values stated in ticks (100 nanoseconds), where the minimal accuracy required is a
+        /// microsecond, the proper value for lowestTrackableValue would be 10.
+        /// </remarks>
         public ShortHistogram(long instanceId, long lowestTrackableValue, long highestTrackableValue,
                          int numberOfSignificantValueDigits)
             : base(instanceId, lowestTrackableValue, highestTrackableValue, numberOfSignificantValueDigits)

Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ private static void RecordMeasurements()`
`49`	`49`	`}`
`50`	`50`
`51`	`51`	`/// <summary>`
`52`		`- /// Write to the console the Memory footprint of the histogram instance and`
	`52`	`+ /// Write to the console the memory footprint of the histogram instance and`
`53`	`53`	`/// the percentile distribution of all the recorded values.`
`54`	`54`	`/// </summary>`
`55`	`55`	`private static void OutputMeasurements()`