Castle Game Engine

Class TCastleProfiler

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleTimeUtils

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);

    An alternative way to display the profile is to pass True as a 2nd argument to any Stop call. This allows to display a profile limited to given Start .. Stop pair.

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://castle-engine.io/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

Overview

Methods

Public constructor Create;
Public destructor Destroy; override;
Public function Summary: string;
Public procedure Clear; deprecated 'This method is not reliable (may cause crashes when used between Start/Stop) and also not comfortable. To display partial profile information, better use Stop with 2nd argument true.';
Public function Start(const Description: String): TCastleProfilerTime;
Public procedure Stop(const TimeStart: TCastleProfilerTime; const LogSummary: Boolean = false);

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; deprecated 'This method is not reliable (may cause crashes when used between Start/Stop) and also not comfortable. To display partial profile information, better use Stop with 2nd argument true.';

Warning: this symbol is deprecated: This method is not reliable (may cause crashes when used between Start/Stop) and also not comfortable. To display partial profile information, better use Stop with 2nd argument true.

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 behavior 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.) So, you do not really have to wrap this in "try ... finally ... end" clause, if it's acceptable that the profiler output is useless in exceptional situations.

See also
Stop
Stop a task.
Public procedure Stop(const TimeStart: TCastleProfilerTime; const LogSummary: Boolean = false);

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

If LogSummary, and profiling is Enabled, we will output (to CastleLog) a summary of things that happened within this particular TCastleProfilerTime instance (between it's start and stop). This is useful when you are interested not only in adding this TCastleProfilerTime to the profiler tree, but also in immediately viewing the times in this TCastleProfilerTime subtree.

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.16.0.