#region Apache License 2.0
/*
Nuclex .NET Framework
Copyright (C) 2002-2024 Markus Ewald / Nuclex Development Labs

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/
#endregion // Apache License 2.0

using System;
using System.Threading;
using System.Windows.Forms;

namespace Nuclex.Windows.Forms {

  /// <summary>Progress bar with optimized multi-threading behavior</summary>
  /// <remarks>
  ///   <para>
  ///     If a background thread is generating lots of progress updates, using synchronized
  ///     calls can drastically reduce performance. This progress bar optimizes that case
  ///     by performing the update asynchronously and keeping only the most recent update
  ///     when multiple updates arrive while the asynchronous update call is still running.
  ///   </para>
  ///   <para>
  ///     This design eliminates useless queueing of progress updates, thereby reducing
  ///     CPU load occuring in the UI thread and at the same time avoids blocking the
  ///     worker thread, increasing its performance.
  ///   </para>
  /// </remarks>
  public partial class AsyncProgressBar : ProgressBar {

    /// <summary>Initializes a new asynchronous progress bar</summary>
    public AsyncProgressBar() {
      InitializeComponent();

      this.Disposed += new EventHandler(progressBarDisposed);
      this.updateProgressDelegate = new MethodInvoker(updateProgress);

      // Could probably use VolatileWrite() as well, but for consistency reasons
      // this is an Interlocked call, too. Mixing different synchronization measures
      // for a variable raises a red flag whenever I see it :)
      Interlocked.Exchange(ref this.newProgress, -1.0f);
    }
    
    /// <summary>Called when the progress bar is being disposed</summary>
    /// <param name="sender">Progress bar that is being disposed</param>
    /// <param name="arguments">Not used</param>
    private void progressBarDisposed(object sender, EventArgs arguments) {

      // CHECK: This method is only called on an explicit Dispose() of the control.
      //   It is legal to call Control.BeginInvoke() without calling Control.EndInvoke(),
      //   so the code is quite correct even if no Dispose() occurs, but is it also clean?
      //   http://www.interact-sw.co.uk/iangblog/2005/05/16/endinvokerequired

      // Since this has to occur in the UI thread, there's no way that updateProgress()
      // could be executing just now. But the final call to updateProgress() will not
      // have EndInvoke() called on it yet, so we do this here before the control
      // is finally disposed.
      if(this.progressUpdateAsyncResult != null) {
        EndInvoke(this.progressUpdateAsyncResult);
        this.progressUpdateAsyncResult = null;
      }

    }

    /// <summary>Asynchronously updates the value to be shown in the progress bar</summary>
    /// <param name="value">New value to set the progress bar to</param>
    /// <remarks>
    ///   This will schedule an asynchronous update of the progress bar in the UI thread.
    ///   If you change the progress value again before the progress bar has completed its
    ///   update cycle, the original progress value will be skipped and the progress bar
    ///   jumps directly to the latest progress value. Updates are not queued, there is
    ///   at most one update waiting on the UI thread. It is also strictly guaranteed that
    ///   the last most progress value set will be shown and never skipped.
    /// </remarks>
    public void AsyncSetValue(float value) {

      // Update the value to be shown on the progress bar. If this happens multiple
      // times, that's not a problem, the progress bar updates as fast as it can
      // and always tries to show the most recent value assigned.
      float oldValue = Interlocked.Exchange(ref this.newProgress, value);

      // If the previous value was -1, the UI thread has already taken out the most recent
      // value and assigned it (or is about to assign it) to the progress bar control.
      // In this case, we'll wait until the current update has completed and immediately
      // begin the next update - since we know that the value the UI thread has extracted
      // is no longer the most recent one.
      if(oldValue == -1.0f) {
        if(this.progressUpdateAsyncResult != null) {
          EndInvoke(this.progressUpdateAsyncResult);
        }

        this.progressUpdateAsyncResult = BeginInvoke(this.updateProgressDelegate);
      }

    }

    /// <summary>Synchronously updates the value visualized in the progress bar</summary>
    private void updateProgress() {

      // Cache these to shorten the code that follows :)
      int minimum = base.Minimum;
      int maximum = base.Maximum;

      // Take out the most recent value that has been given to the asynchronous progress
      // bar up until now and replace it by -1. This enables the updater to see when
      // the update has actually been performed and whether it needs to start a new
      // invocation to ensure the most recent value will remain at the end.
      float progress = Interlocked.Exchange(ref this.newProgress, -1.0f);

      // Restrain the value to the progress bar's configured range and assign it.
      // This is done to prevent exceptions in the UI thread (theoretically the user
      // could change the progress bar's min and max just before the UI thread executes
      // this method, so we cannot validate the value in AsyncSetValue())
      int value = (int)(progress * (maximum - minimum)) + minimum;
      base.Value = Math.Min(Math.Max(value, minimum), maximum);

    }

    /// <summary>New progress being assigned to the progress bar</summary>
    private float newProgress;
    /// <summary>Delegate for the progress update method</summary>
    private MethodInvoker updateProgressDelegate;
    /// <summary>Async result for the invoked control state update method</summary>
    private volatile IAsyncResult progressUpdateAsyncResult;

  }

} // namespace Nuclex.Windows.Forms