Adding TokenBucket implementation

Author: jarroda

TwentyTwenty.BaseLine.sln

@@ -7,6 +7,10 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{B24C04AA-739
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TwentyTwenty.BaseLine", "src\TwentyTwenty.BaseLine\TwentyTwenty.BaseLine.csproj", "{949D9C42-4EC9-4F6C-AFE7-F0F70DDB56AB}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{7A8BC93C-05C5-4EEE-944F-364AED32DE46}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "TwentyTwenty.BaseLine.Tests", "test\TwentyTwenty.BaseLine.Tests\TwentyTwenty.BaseLine.Tests.csproj", "{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -32,8 +36,21 @@ Global
 		{949D9C42-4EC9-4F6C-AFE7-F0F70DDB56AB}.Release|x64.Build.0 = Release|Any CPU
 		{949D9C42-4EC9-4F6C-AFE7-F0F70DDB56AB}.Release|x86.ActiveCfg = Release|Any CPU
 		{949D9C42-4EC9-4F6C-AFE7-F0F70DDB56AB}.Release|x86.Build.0 = Release|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Debug|x64.Build.0 = Debug|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Debug|x86.Build.0 = Debug|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Release|Any CPU.Build.0 = Release|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Release|x64.ActiveCfg = Release|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Release|x64.Build.0 = Release|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Release|x86.ActiveCfg = Release|Any CPU
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{949D9C42-4EC9-4F6C-AFE7-F0F70DDB56AB} = {B24C04AA-739A-4AAB-B60E-6FA5BB07355F}
+		{83EA4B8B-C5EF-456B-A4A2-CF9DB07B81D8} = {7A8BC93C-05C5-4EEE-944F-364AED32DE46}
 	EndGlobalSection
 EndGlobal

src/TwentyTwenty.BaseLine/RateLimiting/FixedIntervalRefillStrategy.cs

@@ -0,0 +1,45 @@
+using System;
+
+namespace TwentyTwenty.BaseLine.RateLimiting
+{
+    /// <summary>
+    /// A token bucket refill strategy that will provide N tokens for a token bucket to consume every T units of time.
+    /// The tokens are refilled in bursts rather than at a fixed rate.  This refill strategy will never allow more than
+    /// N tokens to be consumed during a window of time T.
+    /// </summary>
+    public class FixedIntervalRefillStrategy : IRefillStrategy
+    {
+        private readonly Ticker _ticker;
+        private readonly long _numTokens;
+        private readonly long _periodInTicks;
+        private long _nextRefillTime;
+        private readonly object _syncRoot = new object();
+
+        /// <summary>Create a FixedIntervalRefillStrategy.</summary>
+        /// <param name="ticker">A ticker to use to measure time.</param>
+        /// <param name="numTokens">The number of tokens to add to the bucket every interval.</param>
+        /// <param name="period">How often to refill the bucket.</param>
+        public FixedIntervalRefillStrategy(Ticker ticker, long numTokens, TimeSpan period)
+        {
+            _ticker = ticker;
+            _numTokens = numTokens;
+            _periodInTicks = period.Ticks;
+            _nextRefillTime = -1;
+        }
+
+        public long Refill()
+        {
+            lock (_syncRoot)
+            {
+                var now = _ticker.Read();
+                if (now < _nextRefillTime)
+                {
+                    return 0;
+                }
+                var refillAmount = Math.Max((now - _nextRefillTime) / _periodInTicks, 1);
+                _nextRefillTime += _periodInTicks * refillAmount;
+                return _numTokens * refillAmount;
+            }
+        }
+    }
+}

src/TwentyTwenty.BaseLine/RateLimiting/IRefillStrategy.cs

@@ -0,0 +1,12 @@
+namespace TwentyTwenty.BaseLine.RateLimiting
+{
+    /// <summary>
+    /// Encapsulation of a refilling strategy for a token bucket.
+    /// </summary>
+    public interface IRefillStrategy
+    {
+        /// <summary>Returns the number of tokens to add to the token bucket.</summary>
+        /// <returns>The number of tokens to add to the token bucket.</returns>
+        long Refill();
+    }
+}

src/TwentyTwenty.BaseLine/RateLimiting/ISleepStrategy.cs

@@ -0,0 +1,13 @@
+namespace TwentyTwenty.BaseLine.RateLimiting
+{
+    /// <summary>
+    /// Encapsulation of a strategy for relinquishing control of the CPU.
+    /// </summary>
+    public interface ISleepStrategy
+    {
+        /// <summary>
+        /// Sleep for a short period of time to allow other threads and system processes to execute.
+        /// </summary>
+        void Sleep();
+    }
+}

src/TwentyTwenty.BaseLine/RateLimiting/ITokenBucket.cs

@@ -0,0 +1,53 @@
+using System.Threading.Tasks;
+
+namespace TwentyTwenty.BaseLine.RateLimiting
+{
+    /// <summary>
+    /// A token bucket is used for rate limiting access to a portion of code.
+    /// 
+    /// See <a href="http://en.wikipedia.org/wiki/Token_bucket">Token Bucket on Wikipedia</a>
+    /// See <a href="http://en.wikipedia.org/wiki/Leaky_bucket">Leaky Bucket on Wikipedia</a>
+    /// </summary>
+    public interface ITokenBucket
+    {
+        /// <summary>
+        /// Attempt to consume a single token from the bucket.  If it was consumed then <code>true</code>
+        /// is returned, otherwise <code>false</code> is returned.
+        /// </summary>
+        /// <returns><code>true</code> if the tokens were consumed, <code>false</code> otherwise.</returns>
+        bool TryConsume();
+
+        /// <summary>
+        /// Attempt to consume a specified number of tokens from the bucket.  If the tokens were consumed then <code>true</code>
+        /// is returned, otherwise <code>false</code> is returned.
+        /// </summary>
+        /// <param name="numTokens">The number of tokens to consume from the bucket, must be a positive number.</param>
+        /// <returns><code>true</code> if the tokens were consumed, <code>false</code> otherwise.</returns>
+        bool TryConsume(long numTokens);
+
+        /// <summary>
+        /// Consume a single token from the bucket.  If no token is currently available then this method will block until a
+        /// token becomes available.
+        /// </summary>
+        void Consume();
+
+        /// <summary>
+        /// Consume a single token from the bucket asynchronously. This method does not block
+        /// <returns>A task that returns once a token has been consumed</returns>
+        /// </summary>
+        Task ConsumeAsync();
+
+        /// <summary>
+        /// Consumes multiple tokens from the bucket.  If enough tokens are not currently available then this method will block
+        /// </summary>
+        /// <param name="numTokens">The number of tokens to consume from the bucket, must be a positive number.</param>
+        void Consume(long numTokens);
+
+        /// <summary>
+        /// Consume multiple tokens from the bucket asynchronously. This method does not block
+        /// <param name="numTokens">The number of tokens to consume from the bucket, must be a positive number.</param>
+        /// <returns>A task that returns once the requested tokens have been consumed</returns>
+        /// </summary>
+        Task ConsumeAsync(long numTokens);
+    }
+}

src/TwentyTwenty.BaseLine/RateLimiting/Ticker.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace TwentyTwenty.BaseLine.RateLimiting
+{
+    public abstract class Ticker
+    {
+        private class SystemTicker : Ticker
+        {
+            public override long Read()
+            {
+                return DateTime.Now.Ticks;
+            }
+        }
+
+        private static readonly Ticker SystemTickerInstance = new SystemTicker();
+
+        public abstract long Read();
+
+        public static Ticker Default()
+        {
+            return SystemTickerInstance;
+        }
+    }
+}

src/TwentyTwenty.BaseLine/RateLimiting/TokenBucket.cs

@@ -0,0 +1,116 @@
+using System;
+using System.Threading.Tasks;
+
+namespace TwentyTwenty.BaseLine.RateLimiting
+{
+    /// <summary>
+    /// A token bucket implementation that is of a leaky bucket in the sense that it has a finite capacity and any added
+    /// tokens that would exceed this capacity will "overflow" out of the bucket and are lost forever.
+    ///
+    /// In this implementation the rules for refilling the bucket are encapsulated in a provided <see cref="IRefillStrategy"/>
+    /// instance.  Prior to attempting to consume any tokens the refill strategy will be consulted to see how many tokens
+    /// should be added to the bucket.
+    ///
+    /// In addition in this implementation the method of yielding CPU control is encapsulated in the provided
+    /// <see cref="ISleepStrategy"/> instance.  For high performance applications where tokens are being refilled incredibly quickly
+    /// and an accurate bucket implementation is required, it may be useful to never yield control of the CPU and to instead
+    /// busy wait.  This strategy allows the caller to make this decision for themselves instead of the library forcing a
+    /// decision.
+    /// </summary>
+    internal class TokenBucket : ITokenBucket
+    {
+        private readonly long _capacity;
+        private readonly IRefillStrategy _refillStrategy;
+        private readonly ISleepStrategy _sleepStrategy;
+        private long _size;
+        private readonly object _syncRoot = new object();
+
+        public TokenBucket(long capacity, IRefillStrategy refillStrategy, ISleepStrategy sleepStrategy)
+        {
+            _capacity = capacity;
+            _refillStrategy = refillStrategy;
+            _sleepStrategy = sleepStrategy;
+            _size = 0;
+        }
+
+        /// <summary>
+        /// Attempt to consume a single token from the bucket.  If it was consumed then <code>true</code>
+        /// is returned, otherwise <code>false</code> is returned.
+        /// </summary>
+        /// <returns><code>true</code> if the tokens were consumed, <code>false</code> otherwise.</returns>
+        public bool TryConsume()
+        {
+            return TryConsume(1);
+        }
+
+        /// <summary>
+        /// Attempt to consume a specified number of tokens from the bucket.  If the tokens were consumed then <code>true</code>
+        /// is returned, otherwise <code>false</code> is returned.
+        /// </summary>
+        /// <param name="numTokens">The number of tokens to consume from the bucket, must be a positive number.</param>
+        /// <returns><code>true</code> if the tokens were consumed, <code>false</code> otherwise.</returns>
+        public bool TryConsume(long numTokens)
+        {
+            if (numTokens <= 0)
+                throw new ArgumentOutOfRangeException("numTokens", "Number of tokens to consume must be positive");
+            if (numTokens > _capacity)
+                throw new ArgumentOutOfRangeException("numTokens", "Number of tokens to consume must be less than the capacity of the bucket.");
+
+            lock (_syncRoot)
+            {
+                // Give the refill strategy a chance to add tokens if it needs to, but beware of overflow
+                var newTokens = Math.Min(_capacity, Math.Max(0, _refillStrategy.Refill()));
+                _size = Math.Max(0, Math.Min(_size + newTokens, _capacity));
+
+                if (numTokens > _size) return false;
+
+                // Now try to consume some tokens
+                _size -= numTokens;
+                return true;
+            }
+        }
+
+        /// <summary>
+        /// Consume a single token from the bucket.  If no token is currently available then this method will block until a
+        /// token becomes available.
+        /// </summary>
+        public void Consume()
+        {
+            Consume(1);
+        }
+
+        /// <summary>
+        /// Consume a single token from the bucket asynchronously. This method does not block
+        /// <returns>A task that returns once a token has been consumed</returns>
+        /// </summary>
+        public Task ConsumeAsync()
+        {
+            return ConsumeAsync(1);
+        }
+
+        /// <summary>
+        /// Consumes multiple tokens from the bucket.  If enough tokens are not currently available then this method will block
+        /// </summary>
+        /// <param name="numTokens">The number of tokens to consume from the bucket, must be a positive number.</param>
+        public void Consume(long numTokens)
+        {
+            while (true) {
+                if (TryConsume(numTokens)) {
+                    break;
+                }
+
+                _sleepStrategy.Sleep();
+            }
+        }
+
+        /// <summary>
+        /// Consume multiple tokens from the bucket asynchronously. This method does not block
+        /// <param name="numTokens">The number of tokens to consume from the bucket, must be a positive number.</param>
+        /// <returns>A task that returns once the requested tokens have been consumed</returns>
+        /// </summary>
+        public Task ConsumeAsync(long numTokens)
+        {
+            return Task.Factory.StartNew(() => Consume(numTokens));
+        }
+    }
+}