///////////////////////////////////////////////////////////////////////////////
//
//  Queue.cs - Example of a thread safe queue class in C♯.
//
//  ©2012, 2014, by Josh Moyer <JMoyer@NODOMAIN.NET>.  All rights reserved.
//
///////////////////////////////////////////////////////////////////////////////

// Possbile work items for this release/milestone or vNext:
// - Events (emtpied, filled, enqueued, dequeued, etc.)
// - C++/CLI for more perf
// - Generics
// - Prioritization
// - Support for IList, IEnumerable or other relevant interfaces

using System;
using System.Threading;

namespace Moyer
{
	public enum QueueStatus
	/// <summary>
	/// Enumeration of return values from instances derived from the <see cref="Queue">Queue</see> class.
	/// </summary>
	/// 
	/// <members>
	///	<member name="Success">The last operation completed successfully.</member>
	///	<member name="Allocation">There was not enough memory to initialze the instance.</member>
	///	<member name="Empty">The queue is empty.</member>
	///	<member name="Full">The queue is full.</member>
	///	<member name="Overrun">The queue was full during the last enqueue operation and overwrote the oldest item.</member>
	///	<member name="Size">The requested queue size is too small.</member>
	///	<member name="Unknown">Represents an unknown error or state.</member>
	/// </members>
	{
		Success = 0,
		Allocation,
		Empty,
		Full,
		Overrun,
		Size,
		Unknown
	}

	public class Queue
	/// <summary>
		/// <spec>
			/// A circular queue of integers of user-specified size using a 
			/// simple array.  Provides routines to initialize(), enqueue() and dequeue()
			/// the queue.  Thread safe. 
		/// </spec>
	/// </summary>

	/// <exception>Function members of this type will not raise exceptions due to performance reasons.  Always check return values when calling function members of this type.</exception>

	/// <remarks>
		/// <list>
			/// <listheader>
				/// Test Plan:
			/// </listheader>
			/// <item>
				/// <list>
					/// <listheader>
						/// With multiple threads of execution on the instance(s) under test:
					/// </listheader>
					/// <item>
						/// <list>
							/// <listheader>
								///	For initialize:
							/// </listheader>
							/// <item>Single and multiple instances.  Verify that all initialize and pass the tests outlined below.</item>
							/// <item>Length &lt; 1 items.  Verify that <see cref="QueueStatus.Size">QueueStatus.Size</see> is returned.</item>
							/// <item>Length = UInt.Maximum items.  Verify that <see cref="QueueStatus.Size">QueueStatus.Size</see> is returned.</item>
							/// <item>Low memory.  Verify that <see cref="QueueStatus.Allocation">QueueStatus.Allocation</see> is returned.</item>
						/// </list>
						/// <list>
							/// <listheader>
								/// For enqueue and dequeue:
							/// </listheader>
							/// <item>Dequeue when empty.  Verify that <see cref="QueueStatus.Empty">QueueStatus.Empty</see> is returned.</item>
							/// <item>Enqueue when full.  Verify that <see cref="QueueStatus.Full">QueueStatus.Full</see> is returned.</item>
							/// <item>Perform operation when full.  Verify that <see cref="QueueStatus.Full">QueueStatus.Full</see> is returned.</item>
							/// <item>Perform operation when empty.  Verify that <see cref="QueueStatus.Empty">QueueStatus.Empty</see> is returned.</item>
							/// <item>Perform operation when head and tail loop across the boundaries of the array.  Verify expected behaviors.</item>
						/// </list>
					/// </item>
				/// </list>
			/// </item>
		/// </list>
	/// </remarks>
	{
		private int[] buffer; 
		private uint head;
		private QueueStatus result;
		private bool nonCircular;
		private uint size;
		private QueueStatus state;
		private uint tail;

		private Queue(uint Size, bool NonCircular)
		{
			// initialize the data members
			buffer = new int[Size];
			head = 0;
			nonCircular = NonCircular;
			size = Size;
			state = QueueStatus.Empty;
			tail = 0;
		}

		public static QueueStatus initialize(ref Queue queue, uint size, bool nonCircular)
		{
			// input check
			if (size < 1) return QueueStatus.Size;

			// attempt to create the queue and return
			try { queue = new Queue(size, nonCircular); }
			catch (OutOfMemoryException) { return QueueStatus.Allocation; }
			catch (Exception) { return QueueStatus.Unknown; }
			return QueueStatus.Success;
		}

		public QueueStatus enqueue(int value)
		{
			// set the default return value
			result = QueueStatus.Success;

			lock (this)
			{
				// check if queue is full
				if (state == QueueStatus.Full)
				{
					if (nonCircular) return QueueStatus.Full;
					else 
					{
						head++;
						result = QueueStatus.Overrun;
					}
				}
							
				// set the value at tail 
				buffer[tail] = value;

				// increment tail
				// restarting the index at the top if necessary
				// and checking for a full queue
				if (++tail == size) tail = 0;
				if (tail == head) state = QueueStatus.Full;
				else state = QueueStatus.Unknown;
			}
			
			// return
			return result;
		}

		public QueueStatus dequeue(ref int value)
		{
			// set the default return value
			result = QueueStatus.Success;
			
			lock (this)
			{
				// check if queue is empty
				if (state == QueueStatus.Empty) return QueueStatus.Empty;
				
				// set the value from head
				value = buffer[head];

				// increment head
				// restarting the index at the top if necessary
				// and checking for an empty queue
				if (++head == size) head = 0;
				if (head == tail) state = QueueStatus.Empty;
				else state = QueueStatus.Unknown;
			}
			
			// return
			return result;
		}
	}
}