HierarchicalProfiler Class

Provides support for hierarchical profiling. (Not available in Silverlight.)

Inheritance Hierarchy

SystemObject
DigitalRune.DiagnosticsHierarchicalProfiler

Namespace: DigitalRune.Diagnostics
Assembly: DigitalRune (in DigitalRune.dll) Version: 1.20.0.0 (1.20.1.14552)

Syntax

C++

Copy

public class HierarchicalProfiler : INamedObject

Public Class HierarchicalProfiler
	Implements INamedObject

public ref class HierarchicalProfiler : INamedObject

type HierarchicalProfiler =  
    class
        interface INamedObject
    end

The HierarchicalProfiler type exposes the following members.

Constructors

	Name	Description
	HierarchicalProfiler	Initializes a new instance of the HierarchicalProfiler class.

Top

Methods

	Name	Description
	Dump	Dumps the profiled data of the given node.
	Equals	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	NewFrame	Must be called when a new frame begins.
	Reset	Resets all timing data.
	Start	Starts time measurement for a node.
	Stop	Stops time measurement for a node.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Properties

	Name	Description
	ElapsedTime	Gets the elapsed time since the creation of this instance or the last Reset.
	FrameCount	Gets the number of frames.
	Name	Gets the name of this profiler.
	Root	Gets the root node.

Top

Remarks

This profiler allows to measure time of method calls and nested method calls, creating a tree structure of time measurements. (Use Profiler instead for simple, non-hierarchical profiling.)

This hierarchical profiler is similar to Profiler but every time Start(String) is called, a HierarchicalProfilerNode is added to a tree of nodes starting with Root. Each node stores the time of a method or code section. The parent of a node represents the method/code section that is the caller. The children of a node represent methods called by the current method. See example.

Conditional Compilation Symbol "DIGITALRUNE_PROFILE": The methods of this class are decorated with the ConditionalAttribute. Compilers that support ConditionalAttribute ignore calls to these methods unless "DIGITALRUNE_PROFILE" is defined as a conditional compilation symbol. That means calling the methods Reset, NewFrame, Start(String) and Stop does not influence execution performance unless the conditional compilation symbol "DIGITALRUNE_PROFILE" is defined. The conditional compilation symbol should be undefined for public, released versions of an application and profiling should only be used during development. (This is similar to the standard .NET class System.Diagnostics.Trace and the conditional compilation symbol "TRACE". See documentation of class System.Diagnostics.Trace.)

Thread-Safety: The HierarchicalProfiler is not thread-safe and single instance of HierarchicalProfiler cannot be used to profile the timing of parallel running code sections.

Examples

Copy

  // The compilation symbol "DIGITALRUNE_PROFILE" must be defined to activate profiling.
  #define DIGITALRUNE_PROFILE

  using System;
  using System.Threading;
  using DigitalRune.Diagnostics;

namespace ProfilingTest
  {
    class Program
    {
      // The profiler instance.
      public static HierarchicalProfiler _profiler = new HierarchicalProfiler("MyProfiler");

      static void Main(string[] args)
      {
        // Start profiling.
        _profiler.Reset();

        // This represents the main-loop of a game.
        for (int i = 0; i < 10; i++)
        {
          // NewFrame() must be called when a new frame of the game begins.
          _profiler.NewFrame();

          Update();
          Draw();
        }

        // Write the profiler data to the console. We start at the root node and include 
        // up to 5 child levels.
        Console.WriteLine(_profiler.Dump(_profiler.Root, 5));
      }

      private static void Update()
      {
        _profiler.Start("Update");

        Physics();
        AI();
        AI();
        AI();
        Thread.Sleep(1);

        _profiler.Stop();
      }

      private static void Physics()
      {
        _profiler.Start("Physics");

        Thread.Sleep(6);

        _profiler.Stop();
      }

      private static void AI()
      {
        _profiler.Start("AI");

        Thread.Sleep(3);

        _profiler.Stop();
      }

      private static void Draw()
      {
        _profiler.Start("Draw");

        Thread.Sleep(4);

         _profiler.Stop();
      }
    }
  }

  /* This program creates following output:
     (The percent values show the time of the node relative to the root of the dump.
     The values in () are Minimum/Average/Maximum times.
     'Other' represents the time of a node that was not measured by a child node.

  Profile 'MyProfiler' Node 'Root' 201.718ms total 10 frames
    Update 79.2% 15.978ms/frame 1 calls/frame (15.838ms/15.978ms/16.006ms)
      Physics 29.8% 6.005ms/frame 1 calls/frame (5.983ms/6.005ms/6.083ms)
      AI 44.3% 8.938ms/frame 3 calls/frame (2.412ms/2.979ms/3.559ms)
      Other 5.1% 10.35ms 1.035ms/frame
    Draw 19.8% 3.984ms/frame 1 calls/frame (3.81ms/3.984ms/4.018ms)
    Other 2.4% 4.787ms 478.69us/frame
  */

Reference

DigitalRune.Diagnostics Namespace