User Guide


Annotation General Characteristics


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++:
  • For Fortran:
    call annotate_site_begin(sitename)
    call annotate_site_end
  • For C#:
    C# and .NET support is deprecated starting
    Intel® Advisor
Any mismatched annotations show up as error during data collection.
For example, if your C/C++ code has an
that is executed, but no corresponding
, 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 (
), 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:
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.


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.

Product and Performance Information


Performance varies by use, configuration and other factors. Learn more at