Intel® Advisor User Guide

ID 766448
Date 3/31/2023
Public

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

Document Table of Contents

Site and Task Annotations for Simple Loops With One Task

Parallel site annotations mark the beginning and end of the parallel site. In contrast, to mark an entire simple loop body as a task, you only need a single iteration task annotation in the common case where the Survey tool identifies a single simple loop that consumes much of an application's time. In many cases, a single time-consuming simple loop structure may be the only task needed within a parallel site. This annotation form is also the easiest to convert to parallel code.

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

If the task's code does not include the entire loop body, or if you need multiple tasks in one parallel site or for complex loops, use the task begin-end annotation pair to mark each task.

Use the general site/task annotation form for time-consuming code not in a loop, for complex loops containing task(s), or cases that require multiple tasks within a parallel site.

Syntax: Simple Loops With One Task

Parallel site annotations mark the parallel site that wraps the loop:

C/C++:

ANNOTATE_SITE_BEGIN(sitename); and ANNOTATE_SITE_END();

Fortran:

call annotate_site_begin(sitename) and call annotate_site_end

C#:

Annotate.SiteBegin(sitename); and Annotate.SiteEnd();

The iteration task annotation occurs within the parallel site. Place this annotation near the start of the loop body to mark an entire simple loop body as a task:

C/C++:

ANNOTATE_ITERATION_TASK(taskname);

Fortran:

call annotate_iteration_task(taskname)

C#:

Annotate.IterationTask(taskname);

For the C/C++ ANNOTATE_SITE_END(); annotation, the sitename argument is optional.

The sitename and taskname must follow the rules for annotation name arguments:

  • For C/C++ code, the sitename must be an ASCII C++ identifier. This should be a name you will recognize when it appears in Intel Advisor tool reports.

  • For Fortran code, the sitename must be a character constant. This should be a name you will recognize when it appears in Intel Advisor tool reports.

  • For C# code, the sitename must be a string. This name should be a string that you will easily remember when it appears in Intel Advisor tool reports.

Examples: Simple Loops With One Task

The following C/C++ code fragment shows a parallel site for a loop with a single task, where the task includes the entire simple loop body:

 ...
   ANNOTATE_SITE_BEGIN(sitename);
   for (i=0; i<N; i++) {
     ANNOTATE_ITERATION_TASK(taskname);
     func(i);
   }
   ANNOTATE_SITE_END();
 ...

The following Fortran code fragment shows a parallel site for a loop with a single task, where the task includes the entire simple loop body:

 ...
 call annotate_site_begin("sitename")
   do i=1,size
     call annotate_iteration_task("taskname")
     call func(i)
   end do
 call annotate_site_end
 ...

The following C# code fragment shows a parallel site for a loop with a single task, where the task includes the entire simple loop body:

 ...
 Annotate.SiteBegin("sitename");
 for (int i = 0; i < N; i++) {
    Annotate.IterationTask("taskname"); 
    func(i);
  }
 Annotate.SiteEnd();
  ...

With Visual Studio projects, parallel sites may span project boundaries, but the parallel sites and their related annotations should be placed within the set of projects that the startup project depends on. You may need to use the Visual Studio* Project Dependencies context menu item to add appropriate dependencies - see the help topic Troubleshooting Unexpected Unmatched Annotations.

The nqueens_Advisor C++ sample and the nqueens_Fortran Fortran sample demonstrate this form of site/task annotations. For example, the C++ annotated code in nqueens_annotated.cpp:

ANNOTATE_SITE_BEGIN(solve);
for(int i=0; i<size; i++) {
  // try all positions in first row
  // create separate array for each recursion
   ANNOTATE_ITERATION_TASK(setQueen);
   // int * queens = new int[size]; //array representing queens placed on a chess ...
   // ADVISOR COMMENT: This is incidental sharing because all the tasks are using ...
   setQueen(queens, 0, i);
}
ANNOTATE_SITE_END();

The help topic Annotating Parallel Sites and Tasks describes adding parallel sites and tasks.