Class TCastleProfiler
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:
Set Enabled to True as early as possible, like in the "initialization" section of your main game unit.
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).
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
 |
constructor Create; |
|
destructor Destroy; override; |
|
function Summary: string; |
|
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.'; |
|
function Start(const Description: String): TCastleProfilerTime; |
|
procedure Stop(const TimeStart: TCastleProfilerTime; const LogSummary: Boolean = false; const LogSummaryOnlyIfNonTrivial: Boolean = false); |
Properties
|
property Enabled: boolean read FEnabled write FEnabled; |
Description
Methods
|
constructor Create; |
|
This item has no description. |
|
destructor Destroy; override; |
|
This item has no description. |
|
function Summary: string; |
|
Summary of the gathered speed measurements.
|
|
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).
|
|
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
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.
|
|
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
|
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-snapshot.