About Annotations

You insert annotations to mark the places in your serial program where Intel® Advisor tools should assume your program's parallel execution and synchronization will occur. Later, after you modify your program to prepare it for parallel execution, you replace these Intel Advisor annotations with parallel framework code so parts of your program can execute in parallel. Identify parts of the loops or functions that use significant CPU time, especially those whose work can be performed independently and distributed amongst multiple cores.

Annotations are either subroutine calls or macro uses, depending on which language you are using, so they can be processed by your current compiler. The annotations do not change the computations of your program, so your application runs normally.

By inserting annotations, you mark proposed parallel code regions for the Intel Advisor tools to examine in detail. The three main types of annotations mark the location of:

  • A parallel site. A parallel site encloses one or more tasks and defines the scope of parallel execution. When converted to a parallel code, a parallel site executes initially using a single thread.

  • One or more parallel tasks within the parallel site. Each task encountered during execution of a parallel site is modeled as being possibly executed in parallel with the other tasks and the remaining code in the parallel site. When converted to parallel code, the tasks will run in parallel. That is, each instance of a task's code may run in parallel on separate cores, and the multiple instances of that task's code also runs in parallel with multiple instances of any other tasks within the same parallel site.

  • Locking synchronization, where mutual exclusion of data access must occur in the parallel program.

In addition, there are:

  • Annotations that stop and resume data collection. Data collection occurs while the target executes. These annotations allow you to skip uninteresting parts of the target program's execution.

  • Special-purpose annotations used in less common cases.

The three Intel Advisor tools recognize the three main types of annotations and the Stop and Resume Collection annotations. Only the Correctness tool processes the special-purpose annotations.

Use the parallel site and task annotations to mark the code regions that are candidates for adding parallelism. These annotations enable the Intel Advisor Suitability and Correctness tools to predict your serial program's parallel behavior. For example:

  • The Suitability tool runs your program and uses parallel site and task boundaries to predict your parallel program's approximate performance characteristics.

  • The Correctness tool runs your program and uses parallel site and task boundaries to check for data races and other data synchronization problems.

One common use of sites and tasks is to enclose an entire loop within a parallel site, and to enclose the body of the loop in a task. For example, the following C/C++ code shows a simple loop that uses two parallel site annotations and one task annotation from the nqueens_Advisor sample. The three inserted annotations and the line that includes the annotation definitions appear in a bold font below.

 #include "advisor-annotate.h"
 void solve() {
 int * queens = new int[size]; //array representing queens placed on a chess board...
  for(int i=0; i<size; i++) {
         // try all positions in first row
    setQueen(queens, 0, i);

The following code from the Fortran nqueens sample shows the use of parallel site and task Fortran annotations, such as call annotate_site_begin("label"). The three inserted annotations and the line that references the annotation definitions module (the use statement) appear in a bold font below.

 use advisor_annotate
! Main solver routine
subroutine solve (queens)
  implicit none
  integer, intent(inout) :: queens(:)
  integer :: i
  call annotate_site_begin("solve")
  do i=1,size
    ! try all positions in first row
    call annotate_iteration_task("setQueen")
    call SetQueen (queens, 1, i)
  end do
  call annotate_site_end

end subroutine solve

The following code from the C# nqueens sample on Windows OS systems shows the use of parallel site and task C# annotations, such as Annotate.SiteBegin("label");. The three inserted annotations and the line that allows use of the annotation definitions (using directive) appear in a bold font below.

 using AdvisorAnnotate;
 public void Solve()
   int[] queens = new int[size]; //array representing queens on a chess board. Index is row position, value is column.
   for (int i = 0; i < size; i++)
     // try all positions in first row
     SetQueen(ref queens, 0, i);

For a list of annotations, see the help topic Summary of Annotation Types (use the link below under See Also).

To simplify inserting annotations:

  • When using the Microsoft Visual Studio* code editor, you can use the Annotation Wizard, as described in Inserting Annotations Using the Annotation Wizard help topic.

  • With any editor, use the annotation assistant in the Survey windows or the No Data message. The annotation assistant displays example annotated code and build settings that you can copy to your application's code.

If you manually type annotations, you should place each annotation on a separate line and use the correct data type for annotation arguments. With C/C++ code, do not place annotations in macros so that references go to the correct source location.

For each source compilation module that contains annotations, in addition to inserting the annotations, you need to:

  • In files where you insert annotations, insert a source line to reference the Intel Advisor file that defines the annotations :

    • For C/C++ modules, include the advisor-annotate.h header file by inserting either #include "advisor-annotate.h" or #include <advisor-annotate.h> (see the help topic Including the Annotations Header File in C/C++ Sources).

    • For Fortran compilation units, insert the use advisor_annotate statement.

    • For C# modules (on Windows* OS), insert the using AdvisorAnnotate; directive.

    For more information, see About Using the Intel Advisor Annotations Definition File.

  • Specify the Intel Advisor include directory when you build your C/C++ or Fortran application, so the compiler can find this include file. Similarly, you need to add the C# annotations definition file to your C# project.

  • For native applications, add the build (compiler and linker) settings. For more information, see the help topic Build Settings... for your specific language.

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