Annotations

Intel® Advisor User Guide

Download PDF

ID 766448

Date 7/13/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-369D460E-05D1-4DD0-91EC-DA9D23122CAD

View Details

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.

NOTE:

In most cases, you do not need source annotations when using Intel® Advisor, except for the Suitability analysis of the Threading perspective. When analyzing your application with other perspectives, such as Vectorization and Code Insights or Offload Modeling, you can analyze all parts of your code automatically or use Intel Advisormark-up capabilities, which do not require you to recompile your application.

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

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 added annotations and the line that allows use of the annotation definitions (using directive) appear in a bold font below.

NOTE:

C# and .NET support is deprecated starting Intel® Advisor 2021.1.

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

To simplify adding annotations:

When using the Microsoft Visual Studio* code editor, you can use the Annotation Wizard.
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.

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>.
- For Fortran compilation units, add the use advisor_annotate statement.
- For C# modules (on Windows* OS), add the using AdvisorAnnotate; directive.
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.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Advisor User Guide

Annotations