Class TCastleProfiler

Description
Hierarchy
Nested Classes and Records
Nested Types
Constants
Fields
Methods
Properties

Unit

ok_nested_2

Declaration

type TCastleProfiler = class(TObject)

Description

This item has no description.

Hierarchy

Overview

Nested Classes and Records

Public TTime = class(TObject)
Public TTimes = class(TTimeList)

Nested Types

Public TTimeList = TObjectList<TTime>;

Constants

Public DefaultFloatPrecision = 2;

Fields

Public var FEnabled: boolean;
Public FFloatPrecision: Cardinal;
Public Times: TTimes;
Public CurrentStack: TTimeList;

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; const LogSummaryOnlyIfNonTrivial: Boolean = false);

Properties

Public property Enabled: boolean read FEnabled write FEnabled;

Description

Nested Types

Public TTimeList = TObjectList<TTime>;

This item has no description.

Constants

Public DefaultFloatPrecision = 2;

This item has no description.

Fields

Public var FEnabled: boolean;

This item has no description.

Public FFloatPrecision: Cardinal;

This item has no description.

Public Times: TTimes;

Collected times tree.

Public CurrentStack: TTimeList;

The currently started (but not stopped) TTime structures.

Methods

Public constructor Create;

This item has no description.

Public destructor Destroy; override;

This item has no description.

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; const LogSummaryOnlyIfNonTrivial: 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.

If LogSummary and LogSummaryOnlyIfNonTrivial, then the summary will be output only if it's larger than some ignorable amount of time (right now: 1 milisecond). This is useful to output only things that take non-trivial amount of time.

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.