Adding Profiling Code

This section show how to add profiling code to your project.

First open the project and parse it, this will activate the "Add Profiling Code" tool button.

Clicking the button adds external method declarations to XPGProfile.dll and plants calls to the profiler at the beginning and end of each method.

{$IFDEF XPGPROFILE}procedure XPGStartProfiling(IsThreaded:boolean); external 'XPGProfile.dll';
procedure XPGStopProfiling(AFileName:string); external 'XPGProfile.dll';
procedure XPGStopProfilingPrompt; external 'XPGProfile.dll';
procedure XPGMethodStart(AId:int64); external 'XPGProfile.dll';
procedure XPGMethodFinish(AId:int64); external 'XPGProfile.dll';
procedure XPGSuspendThread; external 'XPGProfile.dll';
procedure XPGRestartThread; external 'XPGProfile.dll';
{$ENDIF}
implementation

procedure PaintLine(Canvas: TCanvas; I, Len: Integer);
begin
{$IFDEF XPGPROFILE} XPGMethodStart($F19553);try{$ENDIF}

  Canvas.PolyLine([TPoint.Create(0, I * 2 + 1), TPoint.Create(Len, I * 2 + 1)]);

{$IFDEF XPGPROFILE} finally XPGMethodFinish($F19553);end;{$ENDIF}
end;

Note: For projects having the ".Net" switch set method "XPGStopProfiling" declaration is not included. See below for reasons why and how this method can be used within the .Net environment.

Each method is given a unique identifier that maps to its Module, Class and Name. If you add profiling code to this project again each method will be given a different identifier. Profiling data generated using the original identifiers will not be viewable as the map to Module, Class and Name will have been lost. If you do try and re-insert profiling code then a message box appears asking you to confirm this action.

The following sections describe each of these methods.

XPGStartProfiling

Indicates to the profiler it should start recording profiling information from XPGMethodStart and XPGMethodFinish. It takes one Boolean parameter that indicates if it is running in a threaded environment, this protects totalling of profiling code time but is not required and has no effect on user code thread totalling.

A call to this method must be manually added to your code. This gives you the flexability of when to start profiling. For example you probably don't want to record the time taken for a user to enter a set of data but you would want to know how long it takes to process that data. If the processing of the data is initiated in an OnClick handler you would place the method call there.

XPGStopProfiling

Indicates to the profiler it should stop recording information from methods XPGMethodStart and XPGMethodFinish. It takes one String parameter which indicates the file to write the profiling data to. The convension is to use a ".prof" extension for profiling data files.

A call to this method must be manually added to your code.

If the ".Net" switch is set for this project then this methods declaration is not added. This is because the String parameter needs special marshalling when being passed from the .Net environment to a Win32 dll. If you wish to use this method in a .Net environment then you will need to add the following declaration,

[DllImport('XPGProfile.dll', EntryPoint = 'XPGStopProfiling', CharSet = CharSet.Ansi,
       CallingConvention = CallingConvention.stdcall)]
procedure XPGStopProfiling(const AFileName:string);external;

And add the folloing to the USE clause,

System.Runtime.InteropServices

XPGStopProfilingPrompt

Indicates to the profiler it should stop recording information from XPGMethodStart and XPGMethodFinish. It displays a Save dialog prompting you to enter the file and location for storing profiling data. The convension is to use a ".prof" extension for profiling data files.

XPGMethodStart

Calls to this method are automatically generated and you should not manually create a call to this method.

XPGMethodFinish

Calls to this method are automatically generated and you should not manually create a call to this method.

XPGSuspendThread

Suspends recording of information from XPGMethodStart and XPGMethodFinish. This may be required if you wish to remove some method calls which distort or obscure profiling times. For example if the TThread.Synchronize(proc) is used in an application to update the main form, the call injects the "proc" method call into the main VCL thread. This causes the method call time for "proc" to be duplicated, it is recorded once in the method that calls Synchronize (because it has to wait until "proc" finishs) and once in "proc" itself.

In the Demos\Threads\ThrdDemo.dpr project you would place calls to XPGSuspendThread and XPGRestartThread around the call to Synchronize e.g.

procedure TSortThread.VisualSwap(A, B, I, J: Integer);
begin
{$IFDEF XPGPROFILE} XPGMethodStart($2000001F19553);try{$ENDIF}

  FA := A;
  FB := B;
  FI := I;
  FJ := J;
  XPGSuspendThread;
  Synchronize(DoVisualSwap);
  XPGRestartThread

{$IFDEF XPGPROFILE} finally XPGMethodFinish($2000001F19553);end;{$ENDIF}
end;

XPGRestartThread

Restart recording information from XPGMethodStart and XPGMethodFinish after a call to XPGSuspendThread.