Controlling Profiling From Application Code

Applies to AQTime 8.81, last modified on January 18, 2022

AQTime lets you turn profiling on or off from your application’s code. This is useful when areas, triggers and actions do not give you the control you seek, or where they would, but at the cost of some complications, or simply where you want to set triggers or actions from source code rather than from the AQTime user interface.

This topic describes how you can enable or disable profiling from your code.

Basic Concepts

To handle the profiling process from the application code, use the EnableProfiling function that is included in AQTime SDK. To call this function, you need to add certain SDK unit to your application (see below). After that, you can call the function from your code to enable or disable profiling. The function enables or disables profiling according to its boolean parameter:

Visual C++

...
// Enable profiling
EnableProfiling(true);

// Do something
Foo1();
Foo2();
Foo3();

// Disable profiling
EnableProfiling(false);
...

The function enables or disables the profiling status for all the threads of the profiled application. Calling this function has the same effect as using the  Enable/Disable Profiling toolbar and menu item. Note that these commands work only if there is one instance of AQTime running.

How to Call the EnableProfiling Function

  1. Include AQTime SDK unit in your application.

    To call the EnableProfiling function from your code, you need to add the following unit to your application:

    If you use... Add the following file
    Microsoft Visual C# .NET <AQTime 8 SDK>\CS\AQTimeHelpers.cs
    Microsoft Visual Basic .NET <AQTime 8 SDK>\VBNET\AQTimeHelpers.vb
    Microsoft Visual C++, Borland C++Builder, 
    Borland C++ or Intel C++    		 <AQTime 8 SDK>\CPP\Common\AQTimeHelpers.cpp
    Microsoft Visual Basic <AQTime 8 SDK>\VB\AQTimeHelpers.bas
    Borland Delphi <AQTime 8 SDK>\Delphi\Common\AQTimeHelpers.pas
    On Windows Vista and later operating systems AQTime SDK files are located in the <Users>\Public\Documents\AQTime 8 SDK folder. On other operating systems the files reside in the <Documents and Settings>\All Users\Documents\AQTime8 SDK folder.

    Note that the All Users\Documents folder may be displayed in Windows Explorer and the Open and the Save dialogs as All Users\Shared Documents.

  2. Call the function in your code.

    After you link the appropriate SDK unit to your application, you can call the EnableProfiling function from your code. You can try the EnableProfiling function with the sample application, OnOffProfiling, that is part of the AQTime installation (in source). Alternatively, you can try the following sample code in an application of your own. In either case, before running the test, set up the application in AQTime so that the application has full control over profiling:

    • Select All Project Modules and/or Entire .NET Code in AQTime’s Setup panel. For more convenient result analysis, you should uncheck all profiling areas, except for All Project Modules and Entire .NET Code.

    • Be sure the  Enable/Disable Profiling button is not pressed so AQTime does not begin profiling the application by itself.

    Sample code:

    Visual C++

    ...
    // Enable profiling
    EnableProfiling(true);

    // Call your function
    My_Function(Param1, Param2);

    // Disable profiling
    EnableProfiling(false);

    Note that if your application already contains a routine with the name EnableProfiling, you may need to use the AQTimeHelpers namespace or the AQTimeHelpers unit name (this depends on your compiler) when calling the EnableProfiling routine, for example:

    Visual C++

    // Call EnableProfiling using the namespace
    AQTimeHelpers::EnableProfiling(true);

    Delphi

    // Calls EnableProfiling using the unit name
    AQTimeHelpers.EnableProfiling(True);

Tutorial

There is a tutorial that explains how you can control profiling from your application: Enable/Disable Profiling Tutorial. Be sure to read it to gain a better understanding of how it works.

What Functions Get Profiled

AQTime “makes” decision whether to profile a function or not when the application is entering the function. So, if the profiling status is off, AQTime will profile only those function calls that were made after you called EnableProfiling in your code. For instance, if you call EnableProfiling while some function is running and the profiling status for its thread is off, then this function will not be profiled:

Visual C++

// Profiling status is OFF
...
// Some code
for (int i = 0; i < 10; i++)  // Not profiled
  Foo1(i);                    // Not profiled
...
EnableProfiling(true);        // Enable profiling
...
Foo2();                       // Line is not profiled.
...                           // The Foo2 function will be profiled.
 

Similarly, if you call EnableProfiling(false) while some function is running and the profiling status of its thread is on, then the function will still be profiled. If you use line-level profiling, AQTime will profile even those source lines that are after the call to EnableProfiling(false) in the function’s code. However, the calls to the function’s child routines will not be profiled (you will not see them in profiling results).

Visual C++

// Profiling status is ON
...
// Some code
for (int i = 0; i < 10; i++)  // Profiled
  Foo1(i);                    // Profiled
...
EnableProfiling(false);       // Disable profiling
...
Foo2();                       // Line is profiled.
...                           // The Foo2 function will not be profiled.
 

See Also

Running a Profiling Session
Enable/Disable Profiling Tutorial
Using Triggers
Using Actions
Working With AQTime via COM

Highlight search results