Class TCastleProfiler

Unit

Declaration

type TCastleProfiler = class(TObject)

Description

Profiler, to measure the speed of execution of your code. This is usually used only through the singleton Profiler.

The profiler is automatically used by various Castle Game Engine loading routines. It presents the easiest way to answer questions like "which game asset is the most expensive to load".

To get the profile:

  1. Set Enabled to True as early as possible, like in the "initialization" section of your main game unit.

  2. The engine will automatically send to log a profile after TCastleApplication.OnInitialize finished, which is a usual place when loading takes place in simple CGE applications.

    You don't need to do anything, just make sure you have logging enabled (call InitializeLog).

  3. You can display the profile Summary at any point in your application, in any way you like. For example by

    WritelnLogMultiline('Time Profile', Profiler.Summary);

    After displaying the profile, you can clear the profile afterwards by calling Clear, if you prefer the next profile to no longer show what you already output.

To send your own time information to the profile, call Start and Stop methods around a given time-consuming task. We will measure time and automatically build a tree of tasks (when one larger task contains several smaller tasks).

Contrary to profilers like Valgrind or Gprof (see https://castle-engine.io/manual_optimization.php#section_profiling , https://github.com/castle-engine/castle-engine/wiki/Profiling-Using-Valgrind ), this profiler does not automatically gather everything. On the other hand, this profiler works on all platforms supported by CGE, and is trivial to use.

Hierarchy

  • TObject
  • TCastleProfiler

Overview

Methods

Public constructor Create;
Public destructor Destroy; override;
Public function Summary: string;
Public procedure Clear;
Public function Start(const Description: String): TCastleProfilerTime;
Public procedure Stop(const TimeStart: TCastleProfilerTime);

Properties

Public property Enabled: boolean read FEnabled write FEnabled;

Description

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public function Summary: string;

Summary of the gathered speed measurements.

Public procedure Clear;

Clear currently gathered times.

Do not call this when some time measure is started but not yet stopped Currently, this will cause such time measure to be rejected, and stopping it will cause a one-time warning, but don't depend on this exact behaviour in the future. We will always gracefully accept this case (not crash).

Public function Start(const Description: String): TCastleProfilerTime;

Start a task which execution time will be measured. You must later call Stop with the returned TCastleProfilerTime value.

Typical usage looks like this:

procedure TMyClass.LoadSomething;
var
  TimeStart: TCastleProfilerTime;
begin
  TimeStart := Profiler.Start('Loading something (TMyClass)');
  try
    // do the time-consuming loading now...
  finally
    Profiler.Stop(TimeStart);
  end;
end;

If you don't use the "finally" clause to always call the matching Stop, and an exception may occur in LoadSomething, then you will have an unmatched Start / Stop calls. The profiler output is undefined in this case. (However, we guarantee that the profiler will not crash or otherwise cause problems in the application.)

See also
Stop
Stop a task.
Public procedure Stop(const TimeStart: TCastleProfilerTime);

Stop a task. This call must match earlier Start call.

See also
Start
Start a task which execution time will be measured.

Properties

Public property Enabled: boolean read FEnabled write FEnabled;

Whether to gather speed measurements. When not enabled, the Start and Stop methods do as little as possible to not waste time.


Generated by PasDoc 0.15.0.