CodeSnip Old Code (SVN)

{
 * This Source Code Form is subject to the terms of the Mozilla Public License,
 * v. 2.0. If a copy of the MPL was not distributed with this file, You can
 * obtain one at http://mozilla.org/MPL/2.0/
 *
 * Copyright (C) 2006-2013, Peter Johnson (www.delphidabbler.com).
 *
 * $Rev$
 * $Date$
 *
 * Implements a class that executes a thread and displays a dialog box if thread
 * takes more than a specified time to complete.
}


unit UWaitForThreadUI;


interface


uses
  // Delphi
  SysUtils, Classes, ExtCtrls, Forms, SyncObjs,
  // Project
  UBaseObjects;


type

  {
  TWaitForThreadUI:
    Class that executes a thread and displays a dialog box if thread takes more
    than a specified time to complete.
  }
  TWaitForThreadUI = class(TNoPublicConstructObject)
  strict private
    const DefaultPauseBeforeDisplay = 50;
    const DefaultMinDisplayTime = 1000;
    var fThread: TThread;               // Thread to be executed
    var fForm: TForm;                   // Form to be displayed if required
    var fMinDisplayTimer: TTimer;       // Timer to delay closure of form
    var fSaveOnTerminate: TNotifyEvent; // Saves fThread.OnTerminate value
    var fSaveFormShow: TNotifyEvent;    // Saves fForm.OnShow value
    var fFormCloseRequested: Boolean;   // Indicates if form is awaiting closure
    var fPauseBeforeDisplay: Cardinal;  // Time before fForm is displayed
    var fThreadTerminated: Boolean;     // Indicates if fThread has terminated
    var fMinTimeElapsed: Boolean;       // True when form displayed long enough
    class var fLock: TCriticalSection;  // Protects form opening / closing
    procedure ThreadTerminated(Sender: TObject);
      {Handles thread's OnTerminate event. Flags thread has terminated and
      requests closure of any displayed form.
        @param Sender [in] Not used.
      }
    procedure MinTimeElapsed(Sender: TObject);
      {Timer event handler called once, when minimum execution time has elapsed.
        @param Sender [in] Not used.
      }
    procedure ShowForm;
      {Displays required form. A critical section ensures that only one thread
      at a time can attempt to show the form.
      }
    procedure CloseForm;
      {Closes any displayed form if thread has terminated and minimum display
      time has elapsed. A critical section ensures that only one thread at a
      time can attempt to close the form.
      }
    procedure FormShowHandler(Sender: TObject);
      {Event handler for fForm.OnShow event. Checks if form can open.
        @param Sender [in] Reference to form triggering event.
      }
    procedure Pause;
      {Delays execution by fPauseBeforeDisplay ms.
      }
  strict protected
    constructor InternalCreate(const AThread: TThread;
      const AForm: TForm; const APauseBeforeDisplay, AMinDisplayTime: Cardinal);
      {Object constructor. Sets up object.
        @param AThread [in] Thread to be executed.
        @param AForm [in] Form to be displayed while thread executes.
        @param APauseBeforeDisplay [in] Time thread given to execute before form
          is displayed (optional)
        @param AMinDisplayTime [in] Minimum time to display form (optional).
      }
    procedure Execute;
      {Executes thread and displays dialog box if necessary.
      }
  public
    class constructor Create;
      {Class constructor. Initialises critical section.
      }
    class destructor Destroy;
      {Class destructor. Destroys critical section.
      }
    destructor Destroy; override;
      {Object destructor. Tears down object.
      }
    class procedure Run(const AThread: TThread; const AForm: TForm;
      const APauseBeforeDisplay: Cardinal = DefaultPauseBeforeDisplay;
      const AMinDisplayTime: Cardinal = DefaultMinDisplayTime); overload;
      {Creates and executes a TWaitForThreadUI object that executes a thread,
      displaying dialog box if necessary.
        @param AThread [in] Thread to be executed.
        @param AForm [in] Form to be displayed while thread executes.
        @param APauseBeforeDisplay [in] Time thread given to execute before form
          is displayed (optional)
        @param AMinDisplayTime [in] Minimum time to display form (optional).
      }
    class procedure Run(const AProc: TProc; const AIsThreadSafe: Boolean;
      const AForm: TForm;
      const APauseBeforeDisplay: Cardinal = DefaultPauseBeforeDisplay;
      const AMinDisplayTime: Cardinal = DefaultMinDisplayTime); overload;
      {Creates and executes a TWaitForThreadUI object that executes a closure in
      a thread, displaying dialog box if necessary.
        @param AProc [in] Closure to be executed in thread.
        @param AIsThreadSage [in] Indicates if AProc is thread safe. If True
          AProc is excuted in context of thread. If False closure is executed
          in context of main thread.
        @param AForm [in] Form to be displayed while thread executes.
        @param APauseBeforeDisplay [in] Time thread given to execute before form
          is displayed (optional)
        @param AMinDisplayTime [in] Minimum time to display form (optional).
      }
  end;


implementation


uses
  // Project
  UExceptions, UUtils;


type
  ///  <summary>Thread class that executes a given closure.</summary>
  TProcThread = class(TThread)
  strict private
    var
      ///  <summary>Closure to executed.</summary>
      fProc: TProc;
      ///  <summary>Flag indicating if closure is thread safe.</summary>
      fProcIsThreadSafe: Boolean;
  strict protected
    ///  <summary>Executes closure from thread.</summary>
    procedure Execute; override;
  public
    ///  <summary>Constructs a new, suspended, thread instance.</summary>
    ///  <param name="Proc">TProc [in] Closure to be executed by thread.</param>
    ///  <param name="ProcIsThreadSafe">Boolean [in] Flag indicating if Proc is
    ///  thread safe or not.</param>
    ///  <remarks>If Proc is not thread safe it is executed in the context of
    ///  the main thread.</remarks>
    constructor Create(const Proc: TProc; const ProcIsThreadSafe: Boolean);
  end;


{ TWaitForThreadUI }

procedure TWaitForThreadUI.CloseForm;
  {Closes any displayed form if thread has terminated and minimum display time
  has elapsed. A critical section ensures that only one thread at a time can
  attempt to close the form.
  }
begin
  fLock.Acquire;
  try
    if not Assigned(fForm) then
      Exit;
    fFormCloseRequested := fThreadTerminated and fMinTimeElapsed;
    if fFormCloseRequested and fForm.Visible then
      fForm.Close;
  finally
    fLock.Release;
  end;
end;

class constructor TWaitForThreadUI.Create;
  {Class constructor. Initialises critical section.
  }
begin
  fLock := TCriticalSection.Create;
end;

destructor TWaitForThreadUI.Destroy;
  {Object destructor. Tears down object.
  }
begin
  fMinDisplayTimer.Free;
  fThread.OnTerminate := fSaveOnTerminate;
  inherited;
end;

class destructor TWaitForThreadUI.Destroy;
  {Class destructor. Destroys critical section.
  }
begin
  fLock.Free;
end;

procedure TWaitForThreadUI.Execute;
  {Executes thread and displays dialog box if necessary.
  }
begin
  // Flag that form closure not yet requested
  fFormCloseRequested := False;
  // Reset termination flags
  fThreadTerminated := False;
  fMinTimeElapsed := False;
  // Execute thread
  fThread.OnTerminate := ThreadTerminated;
  fThread.Start;
  // Pause before displayng dialog by PauseBeforeDisplay ms
  Pause;
  if not fThread.Finished then
    // Show dialog if thread not completed. Dialog blocks until thread
    // terminates.
    ShowForm;
  // Re-raise any exception that was raised by thread: must be a clone and not
  // the original exception.
  if Assigned(fThread.FatalException)
    and (fThread.FatalException is Exception) then
    raise TExceptionHelper.Clone(fThread.FatalException as Exception);
end;

procedure TWaitForThreadUI.FormShowHandler(Sender: TObject);
  {Event handler for fForm.OnShow event. Checks if form can open.
    @param Sender [in] Reference to form triggering event.
  }
begin
  // Call any earler OnShow handler for form
  if Assigned(fSaveFormShow) then
    fSaveFormShow(Sender);
  // If form has already been requested to close then close it
  if fFormCloseRequested then
    fForm.Close;
end;

constructor TWaitForThreadUI.InternalCreate(const AThread: TThread;
  const AForm: TForm; const APauseBeforeDisplay, AMinDisplayTime: Cardinal);
  {Object constructor. Sets up object.
    @param AThread [in] Thread to be executed.
    @param AForm [in] Form to be displayed while thread executes.
    @param APauseBeforeDisplay [in] Time thread given to execute before form is
      displayed (optional)
    @param AMinDisplayTime [in] Minimum time to display form (optional).
  }
begin
  inherited InternalCreate;
  // Set up timer that triggers event when form can close
  fMinDisplayTimer := TTimer.Create(nil);
  fMinDisplayTimer.Enabled := False;
  fMinDisplayTimer.OnTimer := MinTimeElapsed;
  fMinDisplayTimer.Interval := AMinDisplayTime;
  // Record other fields
  fPauseBeforeDisplay := APauseBeforeDisplay;
  fThread := AThread;
  fSaveOnTerminate := AThread.OnTerminate;
  fForm := AForm;
end;

procedure TWaitForThreadUI.MinTimeElapsed(Sender: TObject);
  {Timer event handler called once, when minimum execution time has elapsed.
    @param Sender [in] Not used.
  }
begin
  // Switch off timer
  fMinDisplayTimer.OnTimer := nil;
  fMinDisplayTimer.Enabled := False;
  fMinTimeElapsed := True;
  // Close form
  CloseForm;
end;

procedure TWaitForThreadUI.Pause;
  {Delays execution by fPauseBeforeDisplay ms.
  }
begin
  if fPauseBeforeDisplay = 0 then
    Exit;
  // Busy wait
  UUtils.Pause(fPauseBeforeDisplay);
end;

class procedure TWaitForThreadUI.Run(const AProc: TProc;
  const AIsThreadSafe: Boolean; const AForm: TForm;
  const APauseBeforeDisplay, AMinDisplayTime: Cardinal);
  {Creates and executes a TWaitForThreadUI object that executes a closure in a
  thread, displaying dialog box if necessary.
    @param AProc [in] Closure to be executed in thread.
    @param AIsThreadSage [in] Indicates if AProc is thread safe. If True AProc
      is excuted in context of thread. If False closure is executed in context
      of main thread.
    @param AForm [in] Form to be displayed while thread executes.
    @param APauseBeforeDisplay [in] Time thread given to execute before form is
      displayed (optional)
    @param AMinDisplayTime [in] Minimum time to display form (optional).
  }
var
  ProcThread: TProcThread;  // thread used to execute AProc
begin
  ProcThread := TProcThread.Create(AProc, AIsThreadSafe);
  try
    Run(ProcThread, AForm, APauseBeforeDisplay, AMinDisplayTime);
  finally
    ProcThread.Free;
  end;
end;

class procedure TWaitForThreadUI.Run(const AThread: TThread;
  const AForm: TForm; const APauseBeforeDisplay, AMinDisplayTime: Cardinal);
  {Creates and executes a TWaitForThreadUI object that executes a thread,
  displaying dialog box if necessary.
    @param AThread [in] Thread to be executed.
    @param AForm [in] Form to be displayed while thread executes.
    @param APauseBeforeDisplay [in] Time thread given to execute before form is
      displayed (optional)
    @param AMinDisplayTime [in] Minimum time to display form (optional).
  }
begin
  Assert(Assigned(AThread), ClassName + '.Run: AThread is nil');
  with InternalCreate(AThread, AForm, APauseBeforeDisplay, AMinDisplayTime) do
    try
      Execute;
    finally
      Free;
    end;
end;

procedure TWaitForThreadUI.ShowForm;
  {Displays required form. A critical section ensures that only one thread at a
  time can attempt to show the form.
  }
begin
  fLock.Acquire;
  try
    if not Assigned(fForm) then
      Exit;
    // Start timer that triggers when form is allowed to close after minimum
    // display time. If time is zero we need to trigger ourselves, because
    // timer won't fire.
    fMinDisplayTimer.Enabled := True;
    if fMinDisplayTimer.Interval = 0 then
      MinTimeElapsed(fMinDisplayTimer);
    // Store any existing OnShow event of form and replace with our handler
    fSaveFormShow := fForm.OnShow;
    fForm.OnShow := FormShowHandler;
    try
      // Show form modally if not already requested to close
      if not fFormCloseRequested then
        fForm.ShowModal;
    finally
      // Restore any previous OnShow event handler
      fForm.OnShow := fSaveFormShow;
    end;
  finally
    fLock.Release;
  end;
end;

procedure TWaitForThreadUI.ThreadTerminated(Sender: TObject);
  {Handles thread's OnTerminate event. Flags thread has terminated and requests
  closure of any displayed form.
    @param Sender [in] Not used.
  }
begin
  fThreadTerminated := True;
  CloseForm;
  if Assigned(fSaveOnTerminate) then
    fSaveOnTerminate(fThread);
end;

{ TProcThread }

constructor TProcThread.Create(const Proc: TProc;
  const ProcIsThreadSafe: Boolean);
begin
  Assert(Assigned(Proc), ClassName + '.Create: Proc is nil');
  inherited Create(True);
  fProc := Proc;
  fProcIsThreadSafe := ProcIsThreadSafe;
end;

procedure TProcThread.Execute;
begin
  if fProcIsThreadSafe then
    fProc
  else
    Synchronize(procedure begin fProc; end);
end;

end.