//******************************************************************************************************
//  LogicalThreadOperation.cs - Gbtc
//
//  Copyright © 2015, Grid Protection Alliance.  All Rights Reserved.
//
//  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See
//  the NOTICE file distributed with this work for additional information regarding copyright ownership.
//  The GPA licenses this file to you under the MIT License (MIT), the "License"; you may
//  not use this file except in compliance with the License. You may obtain a copy of the License at:
//
//      http://opensource.org/licenses/MIT
//
//  Unless agreed to in writing, the subject software distributed under the License is distributed on an
//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the
//  License for the specific language governing permissions and limitations.
//
//  Code Modification History:
//  ----------------------------------------------------------------------------------------------------
//  09/24/2015 - Stephen C. Wills
//       Generated original version of source code.
//  02/16/2016 - J. Ritchie Carroll
//       Corrected priority behavior and added override feature, made explicit RunIfPending optional 
//
//******************************************************************************************************

using System;
using System.Threading;

namespace GSF.Threading
{
    /// <summary>
    /// Synchronized operation that executes on a logical thread.
    /// </summary>
    /// <remarks>
    /// This synchronized operation optionally supports a different usage pattern which will
    /// allow for asynchronous loops and signals to be passed between threads throughout an
    /// operation. The following is an example of how to implement a simple asynchronous loop
    /// between two threads using this class. Note that when used, the pattern requires more
    /// diligence on the user's part for handling exceptions and signaling when the operation
    /// is complete:
    /// 
    /// <code>
    /// LogicalThread thread1 = new LogicalThread();
    /// LogicalThread thread2 = new LogicalThread();
    /// 
    /// // Create logical thread operation with manually controlled call to RunIfPending
    /// LogicalThreadOperation operation = new LogicalThreadOperation(thread1, DoOperation, false);
    /// 
    /// private void DoOperation()
    /// {
    ///     ExecuteOnThread1();
    ///     thread2.Push(() => operation.ExecuteAction(() =>
    ///     {
    ///         ExecuteOnThread2();
    ///         operation.RunIfPending();
    ///     }));
    /// });
    /// </code>
    /// </remarks>
    public class LogicalThreadOperation
    {
        #region [ Members ]

        // Constants
        private const int NotRunning = 0;
        private const int Running = 1;
        private const int Pending = 2;

        // Fields
        private readonly LogicalThread m_thread;
        private readonly Action m_action;
        private readonly bool m_autoRunIfPending;
        private int m_priority;

        private int m_state;
        private int m_queuedPriority;
        private CancellationToken m_cancellationToken;

        #endregion

        #region [ Constructors ]

        /// <summary>
        /// Creates a new instance of the <see cref="LogicalThreadOperation"/> class.
        /// </summary>
        /// <param name="thread">The thread on which to execute the operation's action.</param>
        /// <param name="action">The action to be executed.</param>
        /// <param name="autoRunIfPending">
        /// Set to <c>true</c> to execute <see cref="RunIfPending"/> automatically; otherwise,
        /// set to <c>false</c> for user controlled call timing.
        /// </param>
        public LogicalThreadOperation(LogicalThread thread, Action action, bool autoRunIfPending = true)
            : this(thread, action, 1, autoRunIfPending)
        {
        }

        /// <summary>
        /// Creates a new instance of the <see cref="LogicalThreadOperation"/> class.
        /// </summary>
        /// <param name="thread">The thread on which to execute the operation's action.</param>
        /// <param name="action">The action to be executed.</param>
        /// <param name="priority">The priority with which the action should be executed on the logical thread.</param>
        /// <param name="autoRunIfPending">
        /// Set to <c>true</c> to execute <see cref="RunIfPending"/> automatically; otherwise, 
        /// set to <c>false</c> for user controlled call timing.
        /// </param>
        /// <exception cref="ArgumentException"><paramref name="priority"/> is outside the range between 1 and <see cref="LogicalThread.PriorityLevels"/>.</exception>
        public LogicalThreadOperation(LogicalThread thread, Action action, int priority, bool autoRunIfPending = true)
        {
            m_thread = thread;
            m_action = action;
            Priority = priority;
            m_autoRunIfPending = autoRunIfPending;

            // Initialize this class with a cancelled token so that
            // calls to EnsurePriority before the first call to
            // ExecuteActionAsync do not inadvertently queue actions
            m_cancellationToken = new CancellationToken();
            m_cancellationToken.Cancel();
        }

        #endregion

        #region [ Properties ]

        /// <summary>
        /// Gets a value to indicate whether the operation is currently executing actions.
        /// </summary>
        public bool IsRunning => Interlocked.CompareExchange(ref m_state, NotRunning, NotRunning) != NotRunning;

        /// <summary>
        /// Gets a value to indicate whether the operation has an additional operation
        /// that is pending execution after the currently running operation has completed.
        /// </summary>
        public bool IsPending => Interlocked.CompareExchange(ref m_state, NotRunning, NotRunning) == Pending;

        /// <summary>
        /// Gets flag that determines if <see cref="RunIfPending"/> will be called automatically.
        /// </summary>
        public bool AutoRunIfPending => m_autoRunIfPending;

        /// <summary>
        /// Gets or sets default priority for logical thread operation.
        /// </summary>
        /// <exception cref="ArgumentException"><paramref name="value"/> is outside the range between 1 and <see cref="LogicalThread.PriorityLevels"/>.</exception>
        /// <remarks>
        /// Updates to default priority will only take effect during next <see cref="LogicalThread.Push(int, Action)"/> call.
        /// </remarks>
        public int Priority
        {
            get
            {
                return Interlocked.CompareExchange(ref m_priority, 0, 0);
            }
            set
            {
                if (value < 1 || value > m_thread.PriorityLevels)
                    throw new ArgumentException($"Logical thread does not support priority level {value}. Specify a priority between 1 and {m_thread.PriorityLevels}.", nameof(value));

                Interlocked.Exchange(ref m_priority, value);
            }
        }

        #endregion

        #region [ Methods ]

        /// <summary>
        /// Executes the action on the current thread or marks the operation as
        /// pending if the operation is already running.
        /// </summary>
        /// <remarks>
        /// When the operation is marked as pending, it will run again at the next
        /// call to <see cref="RunIfPending"/>. This can be useful if an update to
        /// an object's state has invalidated the operation that is currently running
        /// and will therefore need to be run again.
        /// </remarks>
        public void RunOnce()
        {
            // if (m_state == NotRunning)
            //     TryRunOnce();
            // else if (m_state == Running)
            //     m_state = Pending;

            if (Interlocked.CompareExchange(ref m_state, Pending, Running) == NotRunning)
                TryRunOnce();
        }

        /// <summary>
        /// Executes the action on another thread or marks the operation as pending
        /// if the operation is already running.
        /// </summary>
        /// <remarks>
        /// When the operation is marked as pending, it will run again at the next
        /// call to <see cref="RunIfPending"/>. This can be useful if an update to
        /// an object's state has invalidated the operation that is currently running
        /// and will therefore need to be run again.
        /// </remarks>
        public void RunOnceAsync()
        {
            // if (m_state == NotRunning)
            //     TryRunOnceAsync();
            // else if (m_state == Running)
            //     m_state = Pending;

            if (Interlocked.CompareExchange(ref m_state, Pending, Running) == NotRunning)
                TryRunOnceAsync();
        }

        /// <summary>
        /// Attempts to execute the action on the current thread.
        /// Does nothing if the operation is already running.
        /// </summary>
        public void TryRunOnce()
        {
            // if (m_state == NotRunning)
            // {
            //     m_state = Running;
            //
            //     if (ExecuteAction())
            //         ExecuteActionAsync();
            // }

            if (Interlocked.CompareExchange(ref m_state, Running, NotRunning) == NotRunning)
                ExecuteAction(m_action);
        }

        /// <summary>
        /// Attempts to execute the action on another thread.
        /// Does nothing if the operation is already running.
        /// </summary>
        public void TryRunOnceAsync()
        {
            // if (m_state == NotRunning)
            // {
            //     m_state = Running;
            //     ExecuteActionAsync();
            // }

            if (Interlocked.CompareExchange(ref m_state, Running, NotRunning) == NotRunning)
                ExecuteActionAsync(Priority);
        }

        /// <summary>
        /// Starts the operation over at the beginning if the operation is pending or sets
        /// the operation state back to not running so it can run again.
        /// </summary>
        /// <remarks>
        /// This method must be called at the end of an operation in order to set the state
        /// of the operation back to running or not running so that the operation can run again.
        /// The existence of this method makes this implementation different from other synchronized
        /// operations in that it requires more diligence on the user's part to signal when the
        /// operation is complete. In turn, this allows the user to implement complex operations
        /// that may involve asynchronous loops and signaling patterns that would not be possible
        /// with the <see cref="ISynchronizedOperation"/> interface.
        /// </remarks>
        public void RunIfPending()
        {
            // if (m_state == Pending)
            // {
            //     m_state = Running;
            //     return true;
            // }
            // else if (m_state == Running)
            // {
            //     m_state = NotRunning;
            // }

            if (Interlocked.CompareExchange(ref m_state, NotRunning, Running) == Pending)
            {
                // There is no race condition here because if m_state is Pending,
                // then it cannot be changed by any other line of code except this one
                Interlocked.Exchange(ref m_state, Running);
                ExecuteActionAsync(Priority);
            }
        }

        /// <summary>
        /// Executes an action once on the current thread.
        /// </summary>
        /// <param name="action"><see cref="Action"/> to run on current thread.</param>
        /// <remarks>
        /// This method provides exception handling for the action passed into this
        /// method with a couple of guarantees. The first is that regardless of what
        /// thread is executing the action passed into this method, the exception
        /// will be raised on the thread that the logical operation runs on. The
        /// second is that the RunIfPending method will be called if an exception
        /// does occur in the given action.
        /// </remarks>
        public void ExecuteAction(Action action)
        {
            try
            {
                action();

                if (m_autoRunIfPending)
                    RunIfPending();
            }
            catch (Exception ex)
            {
                if (LogicalThread.CurrentThread != m_thread)
                {
                    m_thread.Push(Priority, () =>
                    {
                        string message = $"Exception occurred while executing logical thread operation: {ex.Message}";
                        throw new Exception(message, ex);
                    });
                }

                RunIfPending();

                if (LogicalThread.CurrentThread == m_thread)
                    throw;
            }
        }

        /// <summary>
        /// If the operation is running, the action has yet to be executed,
        /// and the given priority level differs from the queued action's
        /// priority level, this method will requeue the action at the given
        /// priority level.
        /// </summary>
        /// <param name="priority">The priority at which the current operation should be requeued.</param>
        public void RequeueAction(int priority)
        {
            CancellationToken cancellationToken;
            int queuedPriority;

            // Order of operations here is vital to avoid cancelling freshly
            // queued operations when the user hasn't changed the priority level
            cancellationToken = Interlocked.CompareExchange(ref m_cancellationToken, null, null);
            queuedPriority = Interlocked.CompareExchange(ref m_queuedPriority, 0, 0);

            // If the priority has changed, attempt to cancel the currently queued action.
            // If the action was not previously cancelled, requeue the action at the given priority
            if (queuedPriority != priority && cancellationToken.Cancel())
                ExecuteActionAsync(priority);
        }

        private void ExecuteActionAsync(int priority)
        {
            CancellationToken cancellationToken = new CancellationToken();

            // Order of operations here is vital to avoid getting
            // cancelled when the user hasn't changed the priority level
            Interlocked.Exchange(ref m_queuedPriority, priority);
            Interlocked.Exchange(ref m_cancellationToken, cancellationToken);

            m_thread.Push(priority, () =>
            {
                // If the cancellation token was previously cancelled,
                // it means this action has been requeued so don't do anything.
                // By cancelling it now, we let requeue operations know that the
                // action is currently executing and will soon be requeued anyway
                if (m_cancellationToken.Cancel())
                    ExecuteAction(m_action);
            });
        }

        #endregion
    }
}