2. Annotate Sources

Add Intel Advisor annotations to identify parallel tasks and their enclosing parallel sites.

Before you choose likely places to add parallelism, closely examine the candidate code regions identified by the Survey Report and Survey Source windows. To quickly identify the most time-consuming loops, look for checkmark in the Hot Loops column. Select one possible code region at a time. Look at the execution paths and critical data values. Identify parts of the loops or functions that use significant CPU time, especially those whose work can be performed independently. The goal of adding parallelism is to identify the time-consuming parts of the program and dividing up the work done by these time-consuming statements into multiple tasks, so the parallel program runs faster than its serial counterpart.

To propose code regions where you are considering using parallelism, insert Intel Advisor annotations into your sources. Intel Advisor Suitability and Correctness tools use these annotations to predict the likely parallel characteristics of your application program. You mark your proposed code regions by adding annotations that identify the:

  • Parallel site: A code region that will execute one or more parallel tasks. A parallel site defines the time during which the tasks that it contains will execute. Although execution of a parallel site begins when the program's execution path reaches its beginning, the parallel site terminates only after all tasks that started within it have completed.

  • Parallel task(s): Task code regions will run at the same time as other tasks that execute within the parallel site. A task consists of statement(s) that use a lot of your program's time, usually in a loop or a function call.

    In addition, because each task can have multiple instances of its code running at the same time, examine whether each task uses its data independently.

Site and Task Annotation Example Code

For C/C++ programs, annotations are one-line macro uses. For example:

ANNOTATE_SITE_BEGIN(sitename);

The following C/C++ code shows the use of Intel Advisor parallel site and task C/C++ annotations 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...
  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();
 ...
}
 
      

For Fortran programs, annotations are subroutines that you call, such as:

call annotate_site_begin(sitename)

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 includes the annotation definitions (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 C# programs on Windows systems, annotations are members of a class named Annotate, such as:

Annotate.SiteBegin(sitename); 

On Windows systems, the following code from the C# nqueens sample shows the use of parallel site and task C# annotations, such as Annotate.SiteBegin("label");. The three inserted annotations and the line that includes the annotation definitions appear (using statement) 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.
   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();
 ...
 }

In these cases, the code within the parallel site and code for its task have a single entrance point and single exit point.

Note

Each parallel site and parallel task must have annotations for a single entrance and one or more exit points. You need to add annotations for each exit point, such as C/C++ goto, break, return, or throw statements. This is also true of parallel task begin and end annotations used in parallel sites with multiple tasks.

Intel Advisor Site and Task Annotations

Annotations are recognized by the Suitability and Correctness tools. You insert a begin-end pair of annotations to mark certain code regions, such as a parallel site. Annotations can be processed by your current compiler.

After you decide on the parallel site and its task(s), you need to insert site and task annotations into your sources.

Depending on your task code structure, use one of two types of site and task annotations:

  • A simple loop with only a single task. This is the most common type of type, where a simple loop that requires only a single task, and that single task includes the entire loop body. Whenever possible, start with this simple annotation form, which is shown in the example code below. For a simple loop with one task, you insert three annotations: two site annotations (begin-site and end-site) around a loop and one task annotation.

  • Code whose characteristics require multiple tasks. You may need multiple tasks if separate areas of significant work can be done independently within the same parallel site. Also, there are cases where multiple tasks within a loop can help you meet scalability requirements.

The two types of annotations use the same site annotations, but different task annotations. Simple loops with only a single task require only one task annotation, so the task must consist of the entire loop body. Code in a parallel site with multiple tasks (or if the task is only part of the loop body) require pairs of task annotations to mark the task begin and end boundaries of each task.

For loops, you can start with the task annotations for simple loops with only a single task, run the Suitability tool, and then decide if that loop needs multiple tasks.

Because the annotation label appears in the Intel Advisor tool windows along with the label of other sites and tasks in your program, choose a name you will easily remember. When they are present for an ending annotation (usually not required), the labels for a pair of annotations need to match.

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 (use the link below under See Also).

  • With any editor, use the annotation assistant in the Survey windows or the No Data message. It displays annotated code and build settings that you can copy and paste into your code (use the link below under See Also).

If you manually type annotations, make sure each annotation is on a separate statement line and use the correct data type for annotation arguments.

In addition to inserting the annotations, you also need to specify the Intel Advisor include path when building your program, and insert an include statement (C/C++) , use statement (Fortran), or using statement (C#) to reference the annotations definition file. When building your application, you need to provide the directory location of the annotations definition file as well as certain build options (see the help topic About Using the Intel Advisor Annotations Definition File).

Next Steps

Unless you are already familiar with adding parallelism to serial programs, you should read the help sections starting with About Choosing and Marking the Best Parallel Opportunities before you mark parallel sites and tasks with annotations. For example, you should carefully choose the location and size of each parallel task. Each task can have multiple instances of its code running, and run at the same time as other tasks within the parallel site and the enclosing parallel site itself.

After you add the site and task annotations for each code region(s) where you would consider adding parallelism, proceed to 3. Check Suitability to predict the likely performance characteristics of the annotated sites and tasks.

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