Intel® Advisor User Guide

ID 766448
Date 3/22/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Annotation General Characteristics

Usage

Annotations typically expand to calls to one or more functions, with minimal additional code. When you run the Suitability or Dependencies tools, the calls are instrumented during data collection.

Most annotations must be used in pairs that will execute in a begin-end sequence, such as the parallel site annotations for a site with a single task:

  • For C/C++: ANNOTATE_SITE_BEGIN(sitename); and ANNOTATE_SITE_END();

  • For Fortran: call annotate_site_begin(sitename) and call annotate_site_end

  • For C#: Annotate.SiteBegin(sitename); and Annotate.SiteEnd();

    NOTE:
    C# and .NET support is deprecated starting Intel® Advisor 2021.1.

Any mismatched annotations show up as error during data collection.

For example, if your C/C++ code has an ANNOTATE_SITE_BEGIN(); that is executed, but no corresponding ANNOTATE_SITE_END();, you will see a message, such as: Error: Missing end site when you run the Suitability or Dependencies tool.

You can also use annotations when they are dynamically paired. This lets you annotate code regions that might have more than one exit point. For example, consider this parallel site with multiple tasks:

//Show that an end task annotation should be repeated for a jump out of a loop
ANNOTATE_SITE_BEGIN(for_site1);
  ANNOTATE_TASK_BEGIN(for_taskA);
  for ()
    {
     if()
       ANNOTATE_TASK_END();
       break;
       ANNOTATE_TASK_END();  // unreachable!
    }
       ANNOTATE_TASK_BEGIN(for_taskB);
       ... 
       ANNOTATE_TASK_END();
ANNOTATE_SITE_END();

With C/C++, when you add annotations after a loop that executes only one statement without opening and closing braces ({ and }), add opening and closing braces to allow multi-statement execution of both the original statement and the added annotation statement.

From a program source perspective, the annotation macros expand as a single executable statement (or to nothing if null expansion is used). This allows annotations to be used in locations requiring a single statement safely, as in this example:

  ...
    if (!initialized)
        ANNOTATE_RECORD_ALLOCATION(my_buffer, my_buffer_size);
  ...

Guidelines for Placing Annotations in Source Code

Intel Advisor guidelines for placing annotations in source code are similar to debugger breakpoint limitations. The rules include:

  • Place each annotation on a separate statement line. That is, do not place multiple annotations in a single statement line.

  • With C/C++ code, do not place annotations inside preprocessor macros.

The following shows correct coding using one annotation per statement line:

ANNOTATE_TASK_BEGIN(foo);
 call xyz();
ANNOTATE_TASK_END();

If you do not follow these guidelines, you may see unexpected Unmatched annotations in the Dependencies Report window (see the Troubleshooting topic below) or annotation-related errors in the Suitability Report window.

Semantics

When you run the Suitability or Dependencies tool to collect interactions between your tasks, the execution of annotations and their implications for other operations are tracked by the tool during serial execution, and the results of analysis are displayed in the corresponding Report.

When you run the Dependencies tool, the primary problems of interest are the data interactions that need attention. However, some semantic errors in the use of the annotations in your program may also be reported.