Annotations

You add Intel Advisor annotations to mark the places in serial parts of your 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 annotations with parallel framework code that enables parts of your program to execute in parallel.

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.

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 Dependencies 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 Dependencies 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 Dependencies 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 added 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...
  ANNOTATE_SITE_BEGIN(solve);
  for(int i=0; i<size; i++) {
	 // try all positions in first row
    ANNOTATE_ITERATION_TASK(setQueen);
    setQueen(queens, 0, i);
  }
  ANNOTATE_SITE_END();
 ...
}

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 added 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

For a list of all annotations, see the help topic Summary of Annotation Types.

To simplify adding annotations:

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 - see Copying Annotations and Build Settings Using the Annotation Assistant Pane.

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.

You can experiment by modifying annotations and running the tools again to locate the best places to add parallelism.

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

In files where you add annotations, add 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 adding either #include "advisor-annotate.h" or #include <advisor-annotate.h> (see Including the Annotations Header File in C/C++ Sources).
- For Fortran compilation units, add the use advisor_annotate statement.
- For C# modules (on Windows* OS), add the using AdvisorAnnotate; directive.
For more information, see About Using the 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 (click links under See Also below)

Annotations

See Also