2. Annotate Sources

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

To choose likely places to add parallel execution, examine the code regions identified by the Survey Report window. To quickly identify the most time-consuming loops, look for checkmark in the Hot Loops column. Identify parts of the loops or functions that use significant CPU time, such as a CPU-intensive (hot) loop. For the parallel program to run faster than its serial counterpart, you need to identify the time-consuming parts of the program and define tasks.

To propose parallel code regions where you might use parallelism, add annotations into your sources. Intel Advisor Suitability and Dependencies tools use these annotations to predict the likely parallel characteristics of your program. Each parallel code region (site) executes one or more tasks, where each task's work can be divided up safely amongst multiple cores.

C/C++ 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 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();
 ...
}

Fortran Site and Task Annotation Example Code

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

Intel Advisor Site and Task Annotations

Annotations are recognized by the Suitability and Dependencies tools. You add a begin-end pair of annotations to mark certain code regions, such as a parallel site. Annotations can be processed by your current compiler. 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.

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 (as shown above), where a simple loop requires only a single task, and that single task includes the entire loop body. Whenever possible, start with this simple annotation form. For a simple loop with one task, you add 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.

After you decide on the parallel site and its task(s), add site and task annotations into your sources. In the code examples shown above, 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.

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. For details about these types of site and task annotations, see: Site and Task Annotations for Simple Loops With One Task and Site and Task Annotations for Loops with Multiple Tasks.

Ways to Add Annotations

To simplify adding annotations, use the annotation assistant in the Survey windows or the No Data message. It displays annotated code that you can copy and paste into your sources and build settings you can add to your build scripts.

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

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 needed for an ending annotation, the labels for a pair of annotations need to match.

Next Steps

Unless you are already familiar with adding parallel execution to serial programs, before you mark parallel sites and tasks with annotations consider reading the help sections starting with About Choosing and Marking the Best Parallel Opportunities. For example, you should carefully choose the location and size of each parallel task. Look at the execution paths and critical data values in each candidate task to ensure its work can be performed independently. 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.

In addition to adding the annotations, you also need to specify the Intel Advisor include path when building your program, and add an include statement (C/C++) or use statement (Fortran) 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 About Using the Intel Advisor Annotations Definition File).

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