User Guide

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();
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.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804