Assigning Names to Threads

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

AQTime gathers profiling results per application thread (see Profiling Multiple Threads). To identify a thread in profiling results, AQTime typically uses the thread identifier. For instance, you may see the names like Thread #256, Thread #541 in the Explorer panel. The analysis would be easier if a thread had a more descriptive name. For instance, if you are looking for results of the main application thread, then the name Main Thread is much more useful than Thread #256.

For .NET applications running under the .NET Framework version 2.0 or later, AQTime is able to obtain the user-defined name of a CLR thread assigned through the Thread.Name property. So, using this property you may assign desired names to the CLR threads created in your .NET applications running under the .NET Framework ver. 2.0 (or later).

To assign descriptive names to threads in other applications, use the SetCurrentThreadName function that is defined in the AQTimeHelpers file that is included into the AQTime package (see below). The name assigned to a thread with this function will be used instead of the default thread name in profiling results.

The use of descriptive names for threads will not only simplify the result analysis, but will also improve the merging of results: AQTime will automatically merge the results for those threads that have the same name. Other threads will be included into the merged result set as separate items. For more information about this, see Merging Results.

Note: If you assign custom names to threads for comparison and merging purposes, do not use the names that start with Win32 Thread, CLR Thread or COM Thread. AQTime considers such names as default ones and it will not detect a thread as renamed when they are used.

To assign a name to a thread, follow these steps:

  • Open your application’s project in the development tool you use.

  • Include the AQTimeHelpers file into your application project. This file is located in the following folder:

    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.

    The file holds the declaration of the SetCurrentThreadName function. This function assigns the name to the thread where it is called. It uses the only parameter - the name of a thread to set.

  • Call the SetCurrentThreadName(Name) function in your code (we recommend that you call this routine at the beginning of your thread function). If a thread already has a name, it will be renamed.

    Visual C++

    SetCurrentThreadName("Custom thread name");
    If your application already contains a routine with the name SetCurrentThreadName, you may need to use the AQTimeHelpers namespace or the AQTimeHelpers unit name (this depends on your compiler) when calling the SetCurrentThreadName routine:

    Visual C++

    . . .
    // Calls SetCurrentThreadName using the namespace
    AQTimeHelpers::SetCurrentThreadName("My thread name");

    Delphi

    . .
    // Calls SetCurrentThreadName using the unit name
    AQTimeHelpers.SetCurrentThreadName("My thread name");

  • To obtain the name assigned to the current thread, call GetCurrentThreadName (like SetCurrentThreadName this function is declared in the AQTimeHelpers file).

The OnOffPofiling sample application shipped with AQTime contains code that demonstrates how you can assign descriptive names to threads in your application:

 <AQTime Samples>\Unmanaged\OnOffProfiling\VC2013  -  Microsoft Visual C++ (Visual Studio 2013 project)

 <AQTime Samples>\Unmanaged\OnOffProfiling\VC2005  -  Microsoft Visual C++ (Visual Studio 2005 project)

 <AQTime Samples>\Unmanaged\OnOffProfiling\Delphi  -  Borland Delphi

 <AQTime Samples>\Unmanaged\OnOffProfiling\BCB  -  Borland C++Builder

Note: You can also open Visual Studio samples in later versions of Visual Studio.
On Windows Vista and later, AQTime samples are located in the <Users>\Public\Documents\AQTime 8 Samples folder. On other operating systems, the samples reside in the <Documents and Settings>\All Users\Documents\AQTime 8 Samples folder.

For more information on using this example, see Enable/Disable Profiling Tutorial.

See Also

Profiling Multithreaded Applications
Profiling Multiple Threads
Enable/Disable Profiling Tutorial

Highlight search results