User Guide



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.
In most cases, you do not need source annotations when using
Intel® Advisor
, except for the Suitability analysis of the
perspective. When analyzing your application with other perspectives, such as
Vectorization and Code Insights
Offload Modeling
, you can analyze all parts of your code automatically or use
Intel Advisor
mark-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
sample. The three added annotations and the line that includes the annotation definitions appear in a
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
sample shows the use of parallel site and task Fortran annotations, such as
call annotate_site_begin("
. The three added annotations and the line that references the annotation definitions module (the
statement) appear in a
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#
sample on Windows* OS systems shows the use of parallel site and task C# annotations, such as
. The three added annotations and the line that allows use of the annotation definitions (
directive) appear in a
font below.
C# and .NET support is deprecated starting
Intel® Advisor
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
    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
      header file by adding either
      #include "advisor-annotate.h"
      #include <advisor-annotate.h>
    • For Fortran compilation units, add the
      use advisor_annotate
    • For C# modules (on Windows* OS), add the
      using AdvisorAnnotate;
  • 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.

Product and Performance Information


Performance varies by use, configuration and other factors. Learn more at