General Characteristics of Annotations


Annotations typically expand to calls to one or more functions, with minimal additional code. When you run the Suitability or Correctness 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

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 Correctness 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
  for ()
       ANNOTATE_TASK_END();  // unreachable!

With C/C++, when you insert annotations after a loop that executes only one statement without opening and closing braces ({ and }), insert opening and closing braces to allow multi-statement execution of both the original statement and the inserted 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:

 call xyz();

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


When you run the Suitability or Correctness 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 Correctness 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. Both kinds of problems are documented in About Problem and Message Types (see below).

For more complete information about compiler optimizations, see our Optimization Notice.