/*
* Copyright (c) 2004-2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description: 
*
*/

using System;
using System.Threading;

namespace SymBuildParsingLib.Utils
{
	// <summary>
	// Author: William Stacey (staceyw@mvps.org)
	// Date: 06/10/04
	// The Dijkstra semaphore (also called a counting
	// semaphore) is used to control access to
	// a set of resources. A Dijkstra semaphore
	// has a count associated with it and each
	// Acquire() call reduces the count. A thread
	// that tries to Acquire() the semaphore
	// with a zero count blocks until someone else
	// calls Release() to increase the count.
	// <seealso cref="http://www.fawcette.com/javapro/
	//            2002_02/magazine/features/krangaraju/"/>
	// <seealso cref="http://www.mcs.drexel.edu/~shartley/
	//         MCS361/Lectures/designingJavaSemaphore.html"/>
	// </summary>
	public sealed class SymSemaphore
	{
		#region Constructors
		// <summary>
		// Creates semaphore object with a maxCount
		// and set initial count to maxCount.
		// </summary>
		// <param name="maxCount">
		// Maximum count for the semaphore object.
		// This value must be greater than zero.
		// </param>
		public SymSemaphore(int maxCount) : this(maxCount, maxCount)
		{
		}

		// <summary>
		// Creates semaphore object with
		// a maximum count and initial count.
		// </summary>
		// <param name="maxCount">
		// Maximum count for the semaphore object.
		// This value must be greater than zero.
		// </param>
		// <param name="initialCount">
		// Initial count for the semaphore object.
		// This value must be zero or greater
		// and less than or equal to maximumCount.
		// </param>
		public SymSemaphore(int initialCount, int maxCount)
		{
			if ( initialCount < 0 )
				throw new 
					ArgumentOutOfRangeException("initialCount must be >= 0.");
			if ( maxCount < 1 )
				throw new ArgumentOutOfRangeException("maxCount must be >= 1.");
			if ( initialCount > maxCount)
				throw new 
					ArgumentOutOfRangeException("initialCount" + 
					" must be <= maxCount.");
			count = initialCount;
			this.maxCount = maxCount;
			syncLock = new object();
			starvationLock = new object();
		}

		#endregion

		#region Properties
		// <summary>
		// Gets the current available count (or slots)
		// in the semaphore. A count of zero means that no slots
		// are available and calls to Acquire will block until
		// other thread(s) call Release.
		// Example:
		// A semaphore with a count of 2 will allow
		// 2 more Acquire calls before blocking.
		// </summary>
		public int Count
		{
			get
			{
				lock(syncLock)
				{
					return count;
				}
			}
		}

		// <summary>
		// Gets the maximum count of the semaphore
		// set during construction.
		// </summary>
		public int MaxCount
		{
			get { return maxCount; }
		}

		#endregion

		#region Public Methods

		// <summary>
		// Acquires semaphore and decrements count by 1.
		// If count is zero, this will
		// block indefinitely until another thread executes
		// a Release() to increase the count.
		// </summary>
		// <returns>true if the call returned because
		// the caller reacquired the lock for the
		// specified object. This method does not return
		// if the lock is not reacquired.</returns>
		public bool Wait()
		{
			return Wait(Timeout.Infinite);
		}

		// <summary>
		// Returns a value indicating if Semephore
		// can be acquired within the timeout period.
		// </summary>
		// <returns>true if the lock was acquired before
		// the specified time elapsed; otherwise, false.</returns>
		// <exception cref="ArgumentOutOfRangeException">
		// The value of the millisecondsTimeout parameter
		// is negative, and is not equal to Infinite.
		// </exception>
		public bool Wait(int millisecondsTimeout)
		{
			lock(syncLock)
			{
				// Use spin lock instead of an if test, to handle
				// rogue/barging threads that can enter
				// syncLock before a thread that was notified by a pulse.
				// That rogue thread would
				// decrease the count, then our "Pulsed" thread
				// would regain the lock and continue and
				// decrease the count to -1 which is an error.
				// The while loop/test prevents this.
				while ( count == 0 )
					try
					{
						if (!Monitor.Wait(syncLock, millisecondsTimeout))
							return false;
					}
					catch
					{
						// If we get interupted or aborted,
						// we may have been pulsed before.
						// If we just exit, that pulse would get lost and
						// possibly result in a "live" lock
						// where other threads are waiting
						// on syncLock, and never get a pulse.
						// Regenerate a Pulse as we consumed it.
						// Even if we did not get
						// pulsed, this does not hurt as any thread
						// will check again for count = 0.
						Monitor.Pulse(syncLock);
						// Rethrow the exception for caller.
						// Now semaphore state is same as if
						// this call never happened. Caller must
						// decide how to handle exception.
						throw;
					}
				count--;
				if ( count == 0 )
					lock(starvationLock) { Monitor.PulseAll(starvationLock); }
				return true;
			}
		}

		// <summary>
		// Acquires all the semaphores and brings
		// count to zero. This has the effect
		// of block other threads until we release one or more slots.
		// <seealso cref="Acquire()"/>
		// <seealso cref="ReleaseAll()"/>
		// </summary>
		// <returns>true if the acquired maxCount slots.
		// This method does not return until
		// all slots are acquired.</returns>
		public bool WaitAll()
		{
			// Aquires all slots or blocks for Timeout.Infinite.
			return WaitAll(Timeout.Infinite);
		}

		// <summary>
		// Tries to acquire (maxCount) slots
		// in semaphore. If any single attempt to
		// acquire a semaphore slot exceeds
		// millisecondsTimeout, then return is false.
		// Return is true if we acquire maxCount slots.
		// Normally this method would be paired
		// with the ReleaseAll method.
		// </summary>
		// <param name="millisecondsTimeout"></param>
		// <returns>true if maxCount slots are acquired
		// before the specified time elapsed;
		// otherwise, false.</returns>
		public bool WaitAll(int millisecondsTimeout)
		{
			int slotsGot = 0;
			int elapsedMS = 0;
			DateTime start = DateTime.Now;
			int timeout = millisecondsTimeout;
			for (int i = 0; i < maxCount; i++)
			{
				try
				{
					if (! Wait(timeout) )
					{
						// Could not acquire all slots,
						// release any we may already have got.
						if ( slotsGot > 0 )
							Signal(slotsGot);
						return false;
					}
					else
					{
						elapsedMS = (int)((TimeSpan)
							(DateTime.Now - start)).TotalMilliseconds;
						timeout = millisecondsTimeout - elapsedMS;
						// Next wait will be a smaller timeout.

						if ( timeout < 0 )
							timeout = 0;
						// Next Acquire will return
						// false if we have to wait;

						slotsGot++;
						// If we get all remaining slots
						// with no timeout, we just keep going.
					}
				}
				catch
				{
					// Catch any exception during Acquire wait.
					if ( slotsGot > 0 )
						Signal(slotsGot);
					throw;
				}
			} // end for.
			// Count is not zero, so notify any/all starvation consumers.
			lock(starvationLock) { Monitor.PulseAll(starvationLock); }
			return true;
		}

		// <summary>
		// Increases the count of the semaphore object by one.
		// </summary>
		public void Signal()
		{
			Signal(1);
		}

		// <summary>
		// Increases the count of the semaphore
		// object by a specified amount.
		// </summary>
		// <param name="count">Amount by which the semaphore
		// object's current count is to be increased.</param>
		// <exception cref="ArgumentOutOfRangeException">
		// The releaseCount must be one or greater.
		// </exception>
		// <exception cref="ArgumentOutOfRangeException">
		// The releaseCount would cause
		// the semaphore's count to exceed maxCount. 
		// </exception>
		public void Signal(int releaseCount)
		{
			if ( releaseCount < 1 )
				throw new 
					ArgumentOutOfRangeException("releaseCount must be >= 1.");

			lock(syncLock)
			{
				if ( (count + releaseCount) > maxCount )
					throw new 
						ArgumentOutOfRangeException("releaseCount" + 
						" would cause the semaphore's count to exceed maxCount.");
				count += releaseCount;
				Monitor.PulseAll(syncLock);
			}
		}

		// <summary>
		// Returns indication if we could
		// release one slot in the semaphore.
		// </summary>
		// <returns>true if we released
		// one slot; otherwise false.</returns>
		public bool TryRelease()
		{
			return TryRelease(1);
		}

		// <summary>
		// Returns indication if we could release
		// releaseCount slots in the semaphore.
		// </summary>
		// <param name="releaseCount"></param>
		// <returns>true if we released releaseCount
		// slots; otherwise false.</returns>
		public bool TryRelease(int releaseCount)
		{
			if ( releaseCount <= 0 )
				return false;

			lock(syncLock)
			{
				if ( (count + releaseCount) > maxCount )
					return false;
				else
					count += releaseCount;
				Monitor.PulseAll(syncLock);
				return true;
			}
		}

		// <summary>
		// Releases all remaining semaphores
		// not currently owned. This would normally be
		// called by a thread that previously
		// called AcquireAll(). Note:  Be carefull when
		// using this method as it will release
		// all threads waiting on an Aquire method,
		// which may or may not be what you want.
		// An alternative would be to spin on
		// TryRelease() until it returns false.
		// </summary>
		public void ReleaseAll()
		{
			lock(syncLock)
			{
				count = maxCount;
				Monitor.PulseAll(syncLock);
				// We PulseAll instead of calling pulse
				// with exact number of times needed.
				// This can be slightly inefficient,
				// but is safe and simple.
				// See http://www.mcs.drexel.edu/~shartley/
				//   MCS361/Lectures/designingJavaSemaphore.html
			}
		}

		// <summary>
		// This method blocks the calling thread
		// until the semaphore count drops to zero.
		// A drop to zero will not be recognized
		// if a release happens before this call.
		// You can use this to get notified when
		// semephore's count reaches zero.  This
		// is also known as a "reverse-sensing" semaphore.
		// </summary>
		public void WaitForStarvation()
		{
			lock(starvationLock)
			{
				// We will block until count is 0.
				// We use Interlocked just to be sure
				// we test for zero correctly as we
				// are not in the syncLock context.
				if ( Interlocked.CompareExchange(ref count, 0, 0) != 0 )
					Monitor.Wait(starvationLock);
				// Any Exception during wait will
				// just go to caller.  Do not need to signal
				// any other threads as PulseAll(starvationLock) is used.
				// Also note we don't do a spin
				// while() test as we only care that 
				// count *did go to zero at some instant.
			}
		}
		#endregion

		#region Data members
		// Current count available.
		private int count;
		// Max slots in the semaphore.
		private int maxCount;
		// Object used for sync.
		private readonly object syncLock;
		// Object used for starvation sync.
		private readonly object starvationLock;
		#endregion
	}
}