2. Annotate Sources

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 rowANNOTATE_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 :: icall annotate_site_begin("solve")
  do i=1,size
    ! try all positions in first rowcall annotate_iteration_task("setQueen")
    call SetQueen (queens, 1, i)
  end docall annotate_site_end

end subroutine solve

C# Site and Task Annotation Example Code

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 added 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();
 ...
 }

Intel Advisor Site and Task Annotations

Annotations are recognized by the Suitability and Correctness 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.

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:

• When using the Microsoft Visual Studio* code editor, you can use the Annotation Wizard, as described in Adding Annotations Using the Annotation Wizard.

• 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.

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++) , 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 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.