Click or drag to resize
DigitalRuneProfiler Class
Provides support for simple, non-hierarchical profiling. (Not available in Silverlight.)
Inheritance Hierarchy
SystemObject
  DigitalRune.DiagnosticsProfiler

Namespace: DigitalRune.Diagnostics
Assembly: DigitalRune (in DigitalRune.dll) Version: 1.20.0.0 (1.20.1.14552)
Syntax
public static class Profiler

The Profiler type exposes the following members.

Methods
  NameDescription
Public methodStatic memberAddValue
Adds the value to the ProfilerData with the given name.
Public methodStatic memberClearAll
Removes all profiler data.
Public methodStatic memberDump
Returns a string that contains a table with all ProfilerData instances for the current thread.
Public methodStatic memberDump(Int32)
Returns a string that contains a table with all ProfilerData instances for the given thread.
Public methodStatic memberDump(Thread)
Returns a string that contains a table with all ProfilerData instances for the given thread. (Not available on these platforms: WinRT)
Public methodStatic memberDumpAll
Returns a string that contains all collected profiler data (for all threads).
Public methodStatic memberGet
Gets the ProfilerDataCollection for the current thread.
Public methodStatic memberGet(Int32)
Gets the ProfilerDataCollection for the specified thread.
Public methodStatic memberGet(String)
Gets the ProfilerData with the given name for the current thread.
Public methodStatic memberGet(Thread)
Gets the ProfilerDataCollection for the specified thread. (Not available on these platforms: WinRT)
Public methodStatic memberReset
Resets all ProfilerData for the current thread.
Public methodStatic memberReset(Int32)
Resets all ProfilerData for the given thread.
Public methodStatic memberReset(String)
Resets the ProfilerData with the given name (only for the current thread).
Public methodStatic memberReset(Thread)
Resets all ProfilerData for the given thread. (Not available on these platforms: WinRT)
Public methodStatic memberResetAll
Resets all ProfilerData for all threads.
Public methodStatic memberResetAll(String)
Resets the ProfilerData with the given name for all threads.
Public methodStatic memberCode exampleSetFormat
Sets the formatting data for ProfilerData.
Public methodStatic memberStart
Starts time measurement for the ProfilerData with the given name.
Public methodStatic memberStop
Stops time measurement for the ProfilerData with the given name and records the elapsed time in seconds.
Top
Properties
  NameDescription
Public propertyStatic memberData
Gets the profiler data for each thread.
Top
Remarks

Profilers can be used for simple time measurements of code run-time and to record interesting numbers. (If a hierarchical, more advanced system is desired, HierarchicalProfiler can be used instead.)

New profiling data can be added by calling Start(String)/Stop(String) to measure time, or by calling AddValue(String, Double) to add any other data. For each call of these methods ProfilerData is recorded. ProfilerData is identified by name. The name needs to be specified in the methods Start(String), Stop(String) and Stop(String). The name is user-defined, often the name of the method where the time is measured, or the name of the value added (see example below).

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, ResetAll, Start(String), Stop(String) and AddValue(String, Double) 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.)

Multithreading: The profiler can be used in multithreaded applications. For each thread separate profiler data is collected (see Data). Most methods are thread-safe and work lock-free. Following properties and methods are NOT thread-safe (see property or method description): Data, Get(Int32), ResetAll, ResetAll(String), Reset(Int32), DumpAll, Dump(Int32).

Examples
This example shows how to use the profiler in a simple multithreaded application.
C#
 // The compilation symbol "DIGITALRUNE_PROFILE" must be defined to activate profiling.
 #define DIGITALRUNE_PROFILE

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

 namespace ProfilingTest
 {
   class Program
   {
     static void Main(string[] args)
     {
       // Warmstart: We call Foo and the Parallel class so that all one-time initializations are 
       // done before we start measuring.
       Parallel.For(0, 100, i => Foo());
       Profiler.ResetAll();

       // Measure time of a sequential for-loop.
       Profiler.Start("MainSequential");
       for (int i = 0; i < 100; i++)
         Foo();
       Profiler.Stop("MainSequential");

       // Measure time of a parallel for-loop.
       Profiler.Start("MainParallel");
       Parallel.For(0, 100, i => Foo());
       Profiler.Stop("MainParallel");}

       // Format the output by defining a useful scale. We add descriptions so that any other 
       // developer looking at the output can interpret them more easily.
       Profiler.SetFormat("MainSequential", 1e3f, "[ms]");
       Profiler.SetFormat("MainParallel", 1e3f, "[ms]");
       Profiler.SetFormat("Foo", 1e6f, "[µs]");
       Profiler.SetFormat("ValuesBelow10", 1.0f / 100.0f, "[%]");

       // Print the profiling results.
       Console.WriteLine(Profiler.DumpAll());
       Console.ReadKey();
     }

     public static void Foo()
     {
       Profiler.Start("Foo");

       var random = new Random();
       int numberOfValuesBelow10 = 0;
       for (int i = 0; i < 10000; i++)
       {
         int x = random.Next(0, 100);
         if (x < 10)
           numberOfValuesBelow10++;
       }

       // Profilers can also collect other interesting numbers (not only time). 
       Profiler.AddValue("ValuesBelow10", numberOfValuesBelow10);

       Profiler.Stop("Foo");
     }
   }
 }

/* This writes following output to the console:
(The values after "Thread:" are the thread name and the ManagedThreadId.)

Thread:  (#1)
Name              Calls      Sum          Min        Avg        Max Description
-------------------------------------------------------------------------------
Foo                 127  37895,500    286,800    298,390    385,100 [µs]
ValuesBelow10       127   1271,060      9,700     10,008     10,160 [%]
MainSequential        1     29,834     29,834     29,834     29,834 [ms]
MainParallel          1      8,717      8,717      8,717      8,717 [ms]

Thread: Parallel Worker 0 (#3)
Name              Calls      Sum          Min        Avg        Max Description
-------------------------------------------------------------------------------
Foo                  27   8128,200    288,000    301,044    417,400 [µs]
ValuesBelow10        27    272,640     10,040     10,098     10,160 [%]

Thread: Parallel Worker 1 (#4)
Name              Calls      Sum          Min        Avg        Max Description
-------------------------------------------------------------------------------
Foo                  19   7812,600    340,200    411,189   1307,900 [µs]
ValuesBelow10        19    191,720     10,040     10,091     10,160 [%]

Thread: Parallel Worker 2 (#5)
Name              Calls      Sum          Min        Avg        Max Description
-------------------------------------------------------------------------------
Foo                  27   7998,300    286,800    296,233    326,800 [µs]
ValuesBelow10        27    272,640     10,040     10,098     10,160 [%]

Thread: Parallel Worker 3 (#6)
Name              Calls      Sum          Min        Avg        Max Description
-------------------------------------------------------------------------------
Foo                   0          -          -          -          - [µs]
ValuesBelow10         0          -          -          -          - [%]*/
See Also