Add support for decimals in ValuesGenerator. (dotnet#2547)

* Add support for decimals in ValuesGenerator.
As suggested in the documentation, added support for the decimal type.
Also corrected the documentation to properly enumerate the supported types.
Fixes dotnet#2546

* Add tests to cover supported types in ValueGenerator
Also required updates to ValueGenerator.GenerateValue method to support byte

* Fix compilation errors in AlignedMemory
On newer platforms, the NativeMemory.AlignedAlloc wants UIntPtr not uint arguments

* Addressed review comments

Added a lot of documentation about what public methods do.
Added exceptions when invalid requests of the unique methods for too many distinct values.
Switched to single-line methods for SupportsXXX
Added notes on why we cannot change the existing behavior of supported types, and what the internal methods do (range and values returned).
Added testing coverage for new exceptions

* Fixed documentation

Failed to call out sbyte support in ValuesGenerator

Author: IDisposable

docs/microbenchmark-design-guidelines.md

@@ -368,7 +368,7 @@ T[] Array<T>(int count);
 Dictionary<TKey, TValue> Dictionary<TKey, TValue>(int count)
 ```
 
-As of today, the `T` can be: `byte`, `char`, `int`, `double`, `bool` and `string`. Extending `T` to more types is very welcomed!
+As of today, the `T` can be: `byte`, `sbyte`, `char`, `short`, `ushort`, `int`, `uint`, `long`, `ulong`, `float`, `double`, `bool`, `decimal`, `string`, and `Guid`. Extending `T` to more types is very welcomed!
 
 **Note:** `ValuesGenerator` is simply always creating a new instance of `Random` with a constant seed. It's a crucial component and its correctness is verified using  [Unit Tests](https://github.com/dotnet/performance/blob/main/src/tests/harness/BenchmarkDotNet.Extensions.Tests/UniqueValuesGeneratorTests.cs).
 

src/benchmarks/micro/libraries/Common/AlignedMemory.cs

@@ -24,7 +24,7 @@ private unsafe AlignedMemory(void* memory, int length)
         }
 
         public static unsafe AlignedMemory Allocate(uint length, uint alignment)
-            => new AlignedMemory(NativeMemory.AlignedAlloc(length, alignment), (int)length);
+            => new AlignedMemory(NativeMemory.AlignedAlloc((UIntPtr)length, (UIntPtr)alignment), (int)length);
 
         public bool IsDisposed => _disposed;
 

src/harness/BenchmarkDotNet.Extensions/ValuesGenerator.cs

@@ -14,26 +14,38 @@ public static class ValuesGenerator
     {
         private const int Seed = 12345; // we always use the same seed to have repeatable results!
 
+        /// <summary>
+        /// Returns a T value that is NOT the default(T) (typically zero) value.
+        /// For bool, there's only one choice (true/1).
+        /// For byte/sbyte, will never return byte.MaxValue (256) so there are a maximum of 254 values.
+        /// </summary>
         public static T GetNonDefaultValue<T>()
         {
-            if (typeof(T) == typeof(byte)) // we can't use ArrayOfUniqueValues for byte
-                return Array<T>(byte.MaxValue).First(value => !value.Equals(default));
+            if (typeof(T) == typeof(byte) || typeof(T) == typeof(sbyte)) // we can't use ArrayOfUniqueValues for byte/sbyte (but they have the same range)
+                return Array<T>(byte.MaxValue).First(value => !value.Equals(default(T)));
             else
-                return ArrayOfUniqueValues<T>(2).First(value => !value.Equals(default));
+                return ArrayOfUniqueValues<T>(2).First(value => !value.Equals(default(T)));
         }
 
         /// <summary>
-        /// does not support byte because there are only 256 unique byte values
+        /// Returns an array of the requested size where each entry is a distinct value. 
+        /// For byte and sbyte support a maximum count of 255 because there are only 256
+        /// unique byte values. For bool, there are only 2 values so throw for more requested
         /// </summary>
         public static T[] ArrayOfUniqueValues<T>(int count)
         {
+             if (count > 2 && typeof(T) == typeof(bool))
+                throw new ArgumentOutOfRangeException("count", "Cannot exceed 2 for bool values");
+             if (count > 255 && (typeof(T) == typeof(byte) || typeof(T) == typeof(sbyte)))
+                throw new ArgumentOutOfRangeException("count", "Cannot exceed 255 for byte or sbyte values");
+
             // allocate the array first to try to take advantage of memory randomization
             // as it's usually the first thing called from GlobalSetup method
             // which with MemoryRandomization enabled is the first method called right after allocation
             // of random-sized memory by BDN engine
             T[] result = new T[count];
 
-            var random = new Random(Seed); 
+            var random = new Random(Seed);
 
             var uniqueValues = new HashSet<T>();
 
@@ -49,12 +61,17 @@ public static T[] ArrayOfUniqueValues<T>(int count)
 
             return result;
         }
-        
+
+        /// <summary>
+        /// Returns an array of the requested size where each entry is a random value and values could repeat 
+        /// For byte and sbyte values are built from Random.NextBytes, for other types GenerateValue is used
+        /// to generate a random value in the appropriate range
+        /// </summary>
         public static T[] Array<T>(int count)
         {
             var result = new T[count];
 
-            var random = new Random(Seed); 
+            var random = new Random(Seed);
 
             if (typeof(T) == typeof(byte) || typeof(T) == typeof(sbyte))
             {
@@ -82,6 +99,10 @@ public static T[] Array<T>(int count)
             52, 53, 54, 55, 56, 57, 43, 47          //4..9, +, /
         };
 
+        /// <summary>
+        /// Returns an array of bytes of the requested size where each entry is a random value 
+        /// from the legal subset of ASCII characters used in Base-64 encoded values
+        /// </summary>
         public static byte[] ArrayBase64EncodingBytes(int count)
         {
             var result = new byte[count];
@@ -97,8 +118,18 @@ public static byte[] ArrayBase64EncodingBytes(int count)
             return result;
         }
 
+        /// <summary>
+        /// Returns a Dictionary of the requested size where each entry is a has a distinct key value and
+        /// the stored values are randomly generated. 
+        /// GenerateValue is used to generate a random value in the appropriate range for both the key and value
+        /// </summary>
         public static Dictionary<TKey, TValue> Dictionary<TKey, TValue>(int count)
         {
+            if (count > 2 && typeof(TKey) == typeof(bool))
+                throw new ArgumentOutOfRangeException("count", "Cannot exceed 2 for Dictionary<bool, TValue>");
+            if (count > 255 && (typeof(TKey) == typeof(byte) || typeof(TKey) == typeof(sbyte)))
+                throw new ArgumentOutOfRangeException("count", "Cannot exceed 255 for Dictionary<byte, TValue> or Dictionary<sbyte, TValue>");
+
             var dictionary = new Dictionary<TKey, TValue>();
 
             var random = new Random(Seed);
@@ -114,6 +145,11 @@ public static Dictionary<TKey, TValue> Dictionary<TKey, TValue>(int count)
             return dictionary;
         }
 
+        /// <summary>
+        /// Returns an array of the requested size where each entry is a random string value.
+        /// The values are random length strings within the range requested and are composed
+        /// a random assortment of the letters a..z, A..Z, and digits 0..9
+        /// </summary>
         public static string[] ArrayOfStrings(int count, int minLength, int maxLength)
         {
             var random = new Random(Seed);
@@ -126,36 +162,52 @@ public static string[] ArrayOfStrings(int count, int minLength, int maxLength)
             return strings;
         }
 
+        /// <summary>
+        /// Returns a random of the type requested
+        /// For strings, it will be a random assortment of the letters 'a'..'z', 'A'..'Z', or '0'..'9' that is 1 to 50 characters long
+        /// </summary>
         private static T GenerateValue<T>(Random random)
         {
+            // Note: some of these types (especially the unsigned and values larger than int) are not giving the full range of values.
+            // WE CANNOT change that now because existing performance tests are based on the values returned previously.
+            if (typeof(T) == typeof(byte))
+                return (T)(object)(byte)random.Next(byte.MinValue, byte.MaxValue);      // note: will never return 256 as Random.Next max value is exclusive
+            if (typeof(T) == typeof(sbyte))
+                return (T)(object)(sbyte)random.Next(sbyte.MinValue, sbyte.MaxValue);   // note: will never return 128 as Random.Next max value is exclusive
             if (typeof(T) == typeof(char))
-                return (T)(object)(char)random.Next(char.MinValue, char.MaxValue);
+                return (T)(object)(char)random.Next(char.MinValue, char.MaxValue);      // note: will never return `\uffff` as Random.Next max value is exclusive
             if (typeof(T) == typeof(short))
-                return (T)(object)(short)random.Next(short.MaxValue);
+                return (T)(object)(short)random.Next(short.MaxValue);   // note: will never return short.MaxValue as Random.Next max value is exclusive
             if (typeof(T) == typeof(ushort))
-                return (T)(object)(ushort)random.Next(short.MaxValue);
+                return (T)(object)(ushort)random.Next(short.MaxValue);  // note: will never return short.MaxValue (right in the middle of the domain)
             if (typeof(T) == typeof(int))
-                return (T)(object)random.Next();
+                return (T)(object)random.Next();         // note: cannot call NextInt32 here, because that would change what we've returned in the past
             if (typeof(T) == typeof(uint))
-                return (T)(object)(uint)random.Next();
+                return (T)(object)(uint)random.Next();   // note: cannot call NextInt32 here, because that would change what we've returned in the past
             if (typeof(T) == typeof(long))
-                return (T)(object)(long)random.Next();
+                return (T)(object)(long)random.Next();   // note: will never return a value at or above int.MaxValue
             if (typeof(T) == typeof(ulong))
-                return (T)(object)(ulong)random.Next();
+                return (T)(object)(ulong)random.Next();  // note: will never return a value at or above int.MaxValue because Random.Next never returns negatives
             if (typeof(T) == typeof(float))
                 return (T)(object)(float)random.NextDouble();
             if (typeof(T) == typeof(double))
                 return (T)(object)random.NextDouble();
             if (typeof(T) == typeof(bool))
                 return (T)(object)(random.NextDouble() > 0.5);
+            if (typeof(T) == typeof(decimal))
+                return (T)(object)GenerateRandomDecimal(random);
             if (typeof(T) == typeof(string))
-                return (T)(object)GenerateRandomString(random, 1, 50);
+                return (T)(object)GenerateRandomString(random, 1, 50);  // note: all strings have only the characters 'a'..'z', 'A'..'Z', or '0'..'9'
             if (typeof(T) == typeof(Guid))
-                return (T)(object)GenerateRandomGuid(random);
+                return (T)(object)GenerateRandomGuid(random);   // note: may return malformed Guids (not logically valid per RFC 4122 formatting)
 
             throw new NotImplementedException($"{typeof(T).Name} is not implemented");
         }
-
+     
+        /// <summary>
+        /// Returns a random length strings within the range requested and are composed
+        /// a random assortment of the letters a..z, A..Z, and digits 0..9
+        /// </summary>
         private static string GenerateRandomString(Random random, int minLength, int maxLength)
         {
             var length = random.Next(minLength, maxLength);
@@ -166,21 +218,58 @@ private static string GenerateRandomString(Random random, int minLength, int max
                 var rangeSelector = random.Next(0, 3);
 
                 if (rangeSelector == 0)
-                    builder.Append((char) random.Next('a', 'z'));
+                    builder.Append((char)random.Next('a', 'z'));
                 else if (rangeSelector == 1)
-                    builder.Append((char) random.Next('A', 'Z'));
+                    builder.Append((char)random.Next('A', 'Z'));
                 else
-                    builder.Append((char) random.Next('0', '9'));
+                    builder.Append((char)random.Next('0', '9'));
             }
 
             return builder.ToString();
         }
 
+        /// <summary>
+        /// Returns a randomly generated Guid.
+        /// Note: this is not guaranteed to be a reasonably formatted RFC 4122 Guid, NOR is this
+        /// necessarily a "Version 4 Random" guid. 
+        /// </summary>
         private static Guid GenerateRandomGuid(Random random)
         {
             byte[] bytes = new byte[16];
             random.NextBytes(bytes);
             return new Guid(bytes);
         }
+
+        /// <summary>
+        /// Returns a randomly generated decimal value. 
+        /// Note: returns a value across the entire valid decimal value-space
+        /// </summary>
+        private static decimal GenerateRandomDecimal(Random random)
+        {
+            // Decimal values have a sign, a scale, and 96 bits of significance (lo/mid/high)
+            // generate those parts randomly and assemble a valid decimal
+            byte scale = (byte)random.Next(29);
+            bool sign = random.Next(2) == 0;
+            return new decimal(random.NextInt32(),
+                               random.NextInt32(),
+                               random.NextInt32(),
+                               sign,
+                               scale);
+        }
+       
+        /// <summary>
+        /// Returns a randomly generated int value from the entire range of legal 32-bit integers
+        /// Note: using Random.Next will never return negative values so we can't use that where
+        /// we want the complete bit-space.
+        /// WARNING: Do not use this method in the GenerateValue for the various int-like types
+        /// as that would change the range and order of values returned and THAT would change the
+        /// performance benchmarks
+        /// </summary>
+        private static int NextInt32(this Random random)
+        {
+            int firstBits = random.Next(0, 1 << 4) << 28;
+            int lastBits = random.Next(0, 1 << 28);
+            return firstBits | lastBits;
+        }
     }
 }

src/tests/harness/BenchmarkDotNet.Extensions.Tests/UniqueValuesGeneratorTests.cs

@@ -18,6 +18,8 @@ public void UnsupportedTypesThrow()
         [Fact]
         public void GeneratedArraysContainOnlyUniqueValues()
         {
+            AssertGeneratedArraysContainOnlyUniqueValues<bool>(2);
+            AssertGeneratedArraysContainOnlyUniqueValues<byte>(255);
             AssertGeneratedArraysContainOnlyUniqueValues<int>(1024);
             AssertGeneratedArraysContainOnlyUniqueValues<string>(1024);
         }
@@ -34,6 +36,7 @@ private void AssertGeneratedArraysContainOnlyUniqueValues<T>(int size)
         [Fact]
         public void GeneratedArraysContainAlwaysSameValues()
         {
+            AssertGeneratedArraysContainAlwaysSameValues<byte>(255);
             AssertGeneratedArraysContainAlwaysSameValues<int>(1024);
             AssertGeneratedArraysContainAlwaysSameValues<string>(1024);
         }
@@ -68,9 +71,100 @@ public void GeneratedStringsContainOnlySimpleLettersAndDigits()
         [Fact]
         public void GetNonDefaultValueReturnsNonDefaultValue()
         {
+            Assert.True(ValuesGenerator.GetNonDefaultValue<bool>());
             Assert.NotEqual(default(byte), ValuesGenerator.GetNonDefaultValue<byte>());
             Assert.NotEqual(default(int), ValuesGenerator.GetNonDefaultValue<int>());
             Assert.NotEqual(default(string), ValuesGenerator.GetNonDefaultValue<string>());
         }
+
+        [Fact]
+        public void SupportsByte() => Supports<byte>(255);  // note: testing to a maximum of 255 because byte.MaxValue is never generated
+
+        [Fact]
+        public void ThrowsOnTooManyBytes() => Assert.Throws<ArgumentOutOfRangeException>(() => Supports<byte>(256));
+
+        [Fact]
+        public void SupportsSignedByte() => Supports<sbyte>(127);  // note: testing to a maximum of 127 because sbyte.MaxValue is never generated
+
+        [Fact]
+        public void ThrowsOnTooManySignedBytes() => Assert.Throws<ArgumentOutOfRangeException>(() => Supports<sbyte>(256));
+
+        [Fact]
+        public void SupportsChar() => Supports<char>();
+
+        [Fact]
+        public void SupportsShort() => Supports<short>();
+
+        [Fact]
+        public void SupportsUnsignedShort() => Supports<ushort>();
+
+        [Fact]
+        public void SupportsInteger() => Supports<int>();
+
+        [Fact]
+        public void SupportsUnsignedInteger() => Supports<uint>();
+
+        [Fact]
+        public void SupportsLong() => Supports<long>();
+
+        [Fact]
+        public void SupportsUnsignedLong() => Supports<ulong>();
+
+        [Fact]
+        public void SupportsFloat() => Supports<float>();
+
+        [Fact]
+        public void SupportsDouble() => Supports<double>();
+
+        [Fact]
+        public void SupportsBool() => Supports<bool>(2);
+
+        [Fact]
+        public void ThrowsOnTooManyBools() => Assert.Throws<ArgumentOutOfRangeException>(() => Supports<bool>(3));
+
+        [Fact]
+        public void SupportsDecimal() => Supports<decimal>();
+
+        [Fact]
+        public void SupportsString() => Supports<string>();
+
+        [Fact]
+        public void SupportsGuid() => Supports<Guid>();
+
+        private static void SupportsArray<T>(int count)
+        {
+            var array = ValuesGenerator.Array<T>(count);
+            Assert.NotNull(array);
+            Assert.Equal(count, array.Length);
+        }
+
+        private static void SupportsArrayOfUniques<T>(int count)
+        {
+            var array = ValuesGenerator.ArrayOfUniqueValues<T>(count);
+            Assert.NotNull(array);
+            Assert.Equal(count, array.Length);
+        }
+
+        private static void SupportsNonDefaultValue<T>()
+        {
+            var value = ValuesGenerator.GetNonDefaultValue<T>();
+            Assert.NotEqual(default, value);
+        }
+
+        private static void SupportsDictionary<TKey, TValue>(int count)
+        {
+            var dictionary = ValuesGenerator.Dictionary<TKey, TValue>(count);
+            Assert.NotNull(dictionary);
+            Assert.Equal(count, dictionary.Count);
+        }
+
+        private static void Supports<T>(int count = 10)
+        {
+            SupportsArray<T>(count);
+            SupportsNonDefaultValue<T>();
+            SupportsArrayOfUniques<T>(count);
+            SupportsDictionary<T, T>(count);
+            SupportsDictionary<T, string>(count);
+        }
     }
 }