Promise_Base.cs

using System;
using System.Collections.Generic;
using RSG.Promises;

namespace RSG
{
	public interface IPromiseBase
	{
		/// <summary>
		/// Set the name of the promise, useful for debugging.
		/// </summary>
		IPromiseBase WithName(string name);

		/// <summary>
		/// Completes the promise. 
		/// onResolved is called on successful completion.
		/// onRejected is called on error.
		/// </summary>
		void Done(Action<PromiseResult> onResolved, Action<Exception> onRejected);

		/// <summary>
		/// Completes the promise. 
		/// onResolved is called on successful completion.
		/// Adds a default error handler.
		/// </summary>
		void Done(Action<PromiseResult> onResolved);

		/// <summary>
		/// Complete the promise. Adds a default error handler.
		/// </summary>
		void Done();

		/// <summary>
		/// Handle errors for the promise. 
		/// </summary>
		IPromiseBase Catch(Action<Exception> onRejected);

		/// <summary>
		/// Add a resolved callback that chains a non-value promise.
		/// </summary>
		IPromiseBase Then(Func<PromiseResult, IPromise> onResolved);

		/// <summary>
		/// Add a resolved callback.
		/// </summary>
		IPromiseBase Then(Action<PromiseResult> onResolved);

		/// <summary>
		/// Add a resolved callback and a rejected callback.
		/// The resolved callback chains a non-value promise.
		/// </summary>
		IPromiseBase Then(Func<PromiseResult, IPromise> onResolved, Action<Exception> onRejected);

		/// <summary>
		/// Add a resolved callback and a rejected callback.
		/// </summary>
		IPromiseBase Then(Action<PromiseResult> onResolved, Action<Exception> onRejected);

		/// <summary>
		/// Chain an enumerable of promises, all of which must resolve.
		/// The resulting promise is resolved when all of the promises have resolved.
		/// It is rejected as soon as any of the promises have been rejected.
		/// </summary>
		IPromiseBase ThenAll(Func<IEnumerable<IPromise>> chain);

		/// <summary>
		/// Add a finally callback.
		/// Finally callbacks will always be called, even if any preceding promise is rejected, or encounters an error.
		/// </summary>
		IPromiseBase Finally(Action onComplete);
	}

	/// <summary>
	/// Interface for a promise that can be rejected.
	/// </summary>
	public interface IRejectable
	{
		/// <summary>
		/// Reject the promise with an exception.
		/// </summary>
		void Reject(Exception ex);
	}

	/// <summary>
	/// Arguments to the UnhandledError event.
	/// </summary>
	public class ExceptionEventArgs : EventArgs
	{
		internal ExceptionEventArgs(Exception exception)
		{
			//            Argument.NotNull(() => exception);

			this.Exception = exception;
		}

		public Exception Exception
		{
			get;
			private set;
		}
	}

	/// <summary>
	/// Represents a handler invoked when the promise is rejected.
	/// </summary>
	public struct RejectHandler
	{
		/// <summary>
		/// Callback fn.
		/// </summary>
		public Action<Exception> callback;

		/// <summary>
		/// The promise that is rejected when there is an error while invoking the handler.
		/// </summary>
		public IRejectable rejectable;
	}

	public class PromiseResult
	{
		public static readonly PromiseResult None = new PromiseResult();

		public readonly bool hasValue;
		public readonly object Result;

		public PromiseResult()
		{
			hasValue = false;
		}

		public PromiseResult(object value)
		{
			hasValue = true;
			Result = value;
		}
	}

	/// <summary>
	/// Specifies the state of a promise.
	/// </summary>
	public enum PromiseState
	{
		Pending,    // The promise is in-flight.
		Rejected,   // The promise has been rejected.
		Resolved    // The promise has been resolved.
	};

	/// <summary>
	/// Used to list information of pending promises.
	/// </summary>
	public interface IPromiseInfo
	{
		/// <summary>
		/// Id of the promise.
		/// </summary>
		int Id { get; }

		/// <summary>
		/// Human-readable name for the promise.
		/// </summary>
		string Name { get; }
	}

	public abstract class Promise_Base : IPromiseInfo
	{
		/// <summary>
		/// The exception when the promise is rejected.
		/// </summary>
		protected Exception rejectionException;

		/// <summary>
		/// Error handlers.
		/// </summary>
		protected List<RejectHandler> rejectHandlers;

		/// <summary>
		/// ID of the promise, useful for debugging.
		/// </summary>
		public int Id { get; protected set; }

		/// <summary>
		/// Name of the promise, when set, useful for debugging.
		/// </summary>
		public string Name { get; protected set; }

		/// <summary>
		/// Tracks the current state of the promise.
		/// </summary>
		public PromiseState CurState { get; protected set; }

		public Promise_Base()
		{
			this.CurState = PromiseState.Pending;
			this.Id = ++Promise.nextPromiseId;

			if (Promise.EnablePromiseTracking)
			{
				Promise.pendingPromises.Add(this);
			}
		}

		/// <summary>
		/// Add a rejection handler for this promise.
		/// </summary>
		protected void AddRejectHandler(Action<Exception> onRejected, IRejectable rejectable)
		{
			if (rejectHandlers == null)
			{
				rejectHandlers = new List<RejectHandler>();
			}

			rejectHandlers.Add(new RejectHandler()
			{
				callback = onRejected,
				rejectable = rejectable
			});
		}

		/// <summary>
		/// Invoke a single handler.
		/// </summary>
		protected void InvokeHandler<T>(Action<T> callback, IRejectable rejectable, T value)
		{
			//            Argument.NotNull(() => callback);
			//            Argument.NotNull(() => rejectable);            

			try
			{
				callback(value);
			}
			catch (Exception ex)
			{
				rejectable.Reject(ex);
			}
		}

		protected virtual void ClearHandlers()
		{
			rejectHandlers = null;
		}

		/// <summary>
		/// Invoke all reject handlers.
		/// </summary>
		protected void InvokeRejectHandlers(Exception ex)
		{
			//            Argument.NotNull(() => ex);

			if (rejectHandlers != null)
			{
				rejectHandlers.Each(handler => InvokeHandler(handler.callback, handler.rejectable, ex));
			}

			ClearHandlers();
		}

		/// <summary>
		/// Reject the promise with an exception.
		/// </summary>
		public void Reject(Exception ex)
		{
			//            Argument.NotNull(() => ex);

			if (CurState != PromiseState.Pending)
			{
				throw new ApplicationException("Attempt to reject a promise that is already in state: " + CurState + ", a promise can only be rejected when it is still in state: " + PromiseState.Pending);
			}

			rejectionException = ex;
			CurState = PromiseState.Rejected;

			if (Promise.EnablePromiseTracking)
			{
				Promise.pendingPromises.Remove(this);
			}

			InvokeRejectHandlers(ex);
		}
	}
}