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 Parallel Sites with Multiple Tasks

Parallel site annotations mark the beginning and end of the parallel site. Similarly, begin-end parallel task annotations mark the start and end of each task region. Use this begin-end task annotation pair if there are multiple tasks in a parallel site, if the task code does not include all of the loop body, or for complex loops or code that requires specific task begin-end boundaries, including multiple task end annotations.

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

Syntax: Parallel Sites with Multiple Tasks

Parallel site annotations that mark the parallel site:

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();

Parallel task annotations that mark each task within the parallel site:

C/C++:

ANNOTATE_TASK_BEGIN(taskname); and ANNOTATE_TASK_END();

Fortran:

call annotate_task_begin(taskname) and call annotate_task_end

C#:

Annotate.TaskBegin(taskname); and Annotate.TaskEnd();

For the C/C++ ANNOTATE_TASK_END(); annotation, the taskname argument is optional.

The taskname must follow the rules for annotation name arguments:

  • For C/C++ code, the taskname 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 taskname 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 taskname must be a string. This name should be a string that you will easily remember when it appears in Intel Advisor tool reports.

If you previously used site and task annotations for simple loops with one task and need to convert the task to this general, multiple task form, replace the single iteration loop annotation with a pair of task begin and task end annotations that mark the task region. Both forms use the same parallel site annotations.

Examples: Parallel Site, Multiple Tasks Not in a Loop

The stats C++ sample application shows task parallelism with multiple tasks that are in a parallel site but not in a loop. In this case, several related statements do a lot of computation work and each can be a separate task:

ANNOTATE_SITE_BEGIN(MySite1);
  cout << "Start calculating running average..."<<endl;
  ANNNOTATE_TASK_BEGIN(MyTask1); 
  runningAvg(vals, SIZE, rnAvg);
  ANNOTATE_TASK_END(MyTask1);
    
  cout << "Start calculating running standard deviation..."<<endl;
  ANNOTATE_TASK_BEGIN(MyTask2);
  runningStdDev(vals, SIZE, rnStdDev);
  ANNOTATE_TASK_END(MyTask2);
ANNOTATE_SITE_END(MySite1);

In addition to calling functions that perform the computations, there are other cases where the Survey tool may indicate that a single statement consumes a lot of CPU time. For example, a Fortran array assignment for a very large array.

Examples: Parallel Site, Multiple Tasks Within a Loop

The annotations in the following C/C++ code fragment specify that each iteration of the loop can be two separate tasks, potentially running in parallel with any other iteration and the other task.

 ...
 ANNOTATE_SITE_BEGIN(sitename);
 for (I=0; i<N; I++) {
    ANNOTATE_TASK_BEGIN(task1);
    func1(I);
    ANNOTATE_TASK_END();
    ANNOTATE_TASK_BEGIN(task2);
    func2(I);
    ANNOTATE_TASK_END();
 }
 ANNOTATE_SITE_END();
 ...

The following Fortran code fragment also shows the Fortran site and task annotations, where each iteration of the loop can be two separate tasks, potentially running in parallel with any other iteration and the other task.

 ...
 call annotate_site_begin("sitename ")
   do i=1,size 
      call annotate_task_begin("task1")
      call func1(i)
      call annotate_task_end
      call annotate_task_begin("task2")
      call func2(i)
      call annotate_task_end
   end do
 call annotate_site_end
 ...

The following C# code fragment also shows the C# site and task annotations, where each iteration of the loop can be two separate tasks, potentially running in parallel with any other iteration and the other task.

 ...
 Annotate.SiteBegin("sitename");
 for (int i = 0; i < N; i++) {
   Annotate.TaskBegin("task1");	
   func1(i);
   Annotate.TaskEnd(); 
   Annotate.TaskBegin("task2");	
   func2(i);
   Annotate.TaskEnd();
 }
 Annotate.SiteEnd();
 ...

The code for each task will be marked between task begin and task end annotation pairs inside a parallel site. Code that is not executed in any task is executed by the thread entering the site, which may run in parallel with the identified tasks. In this example, the loop control code that increments i and the compares i with N is assumed to be executed separately from the explicitly specified tasks. This means that you may see conflicts between tasks, and the code outside of any task.

W