Summary of Annotation Types

You can use different kinds of Intel Advisor annotations to mark where you propose to have parallel sites, tasks, locks, or perform special actions. These annotations are:

Parallel site annotations
Parallel task annotations
Parallel lock annotations
Annotations that let you pause and resume data collection
Special-purpose annotations

To be useful, a parallel site must contain at least one task. Code within a parallel task can be executed by multiple threads independently of other instances of itself and also other parallel tasks. Many tasks are code within a loop, or they could be a single statement that does an iterative operation. After you use the Survey or similar profiling tool to locate where your program spends its time, you will see two general types of parallel code regions (parallel sites):

A simple loop that requires only a single task. For the common case where the Survey tool identifies a simple loop structure whose iterations consume much of an application's CPU time and the entire loop body should be a task, you may only need a single task within a parallel site. Unless your time-consuming code is not in a loop or has task(s) in a complex loop, start with this simple form. Add annotations to mark the beginning and end of the parallel site around the loop, and add one task-iteration annotation at the start of the loop body. This annotation form is the easiest to convert to parallel code.
Code whose characteristics require multiple tasks. Depending on the application code characteristics, you may need multiple tasks. For example, you may have statements that can each become separate tasks, or complex or nested loop structures where you need multiple tasks to meet scalability requirements. In this case, add site annotations to mark the beginning and end of the parallel site region and also task annotations that mark the beginning and end of each task.

The two task annotation types use the same parallel site annotations. The following table lists the annotations by category type, including the syntax for the C/C++, Fortran, and C# languages. Each has a link to its detailed description.

Optional arguments are identified using square brackets, such as annotation([int expr]).

Note

To help you add annotations, use the Intel Advisor annotation assistant in the Survey windows or the No Data message to copy and add code snippets. You also need to add the reference to the annotations definitions file.

Brief Description

Name

Site and task annotations for a parallel site that contains a loop with a single task:

Start a parallel site that contains a single task in a loop.

C/C++:	`ANNOTATE_SITE_BEGIN(sitename);`
Fortran:	`call annotate_site_begin(sitename)`
C#:	`Annotate.SiteBegin(sitename);`

Mark an iterative parallel task in a loop. Place this annotation near the start of the loop body within the parallel site's execution.

C/C++:	`ANNOTATE_ITERATION_TASK(taskname);`
Fortran:	`call annotate_iteration_task(taskname)`
C#:	`Annotate.IterationTask(taskname);`

End a parallel site. The parallel site terminates only after all tasks that started within it have completed (see the help topic About Choosing and Marking the Best Parallel Opportunities).

C/C++:	`ANNOTATE_SITE_END([sitename]);` // `sitename` is optional
Fortran:	`call annotate_site_end`
C#:	`Annotate.SiteEnd();`

Site and task annotations for parallel site code that contains multiple tasks (all other situations):

Start a parallel site that contains multiple tasks, or task(s) within non-loop code or complex loop code.

C/C++:	`ANNOTATE_SITE_BEGIN(sitename);`
Fortran:	`call annotate_site_begin(sitename)`
C#:	`Annotate.SiteBegin(sitename);`

Start a parallel task. Must execute within a parallel site that contains multiple tasks, or task(s) within non-loop code or complex loop code.

C/C++:	`ANNOTATE_TASK_BEGIN(taskname);`
Fortran:	`call annotate_task_begin(taskname)`
C#:	`Annotate.TaskBegin(taskname);`

End a parallel task. Must execute within a parallel site that contains multiple tasks, or task(s) within non-loop code or complex loop code.

C/C++:	`ANNOTATE_TASK_END([taskname]);` //`taskname` is optional
Fortran:	`call annotate_task_end`
C#:	`Annotate.TaskEnd();`

End a parallel site. The parallel site terminates only after all tasks that started within it have completed (see the help topic About Choosing and Marking the Best Parallel Opportunities).

C/C++:	`ANNOTATE_SITE_END([sitename]);` // `sitename` is optional
Fortran:	`call annotate_site_end`
C#:	`Annotate.SiteEnd();`

Lock Annotations: describe synchronization locations.

Acquire a lock (0 is a valid address). Must occur within a parallel site.

C/C++:

ANNOTATE_LOCK_ACQUIRE(pointer-expression);

Fortran:

call annotate_lock_acquire(address)

C#:

Annotate.LockAcquire([int expr]);

// this C# argument is optional

Release a lock. Must occur within a parallel site.

C/C++:

ANNOTATE_LOCK_RELEASE(pointer-expression);

Fortran:

call annotate_lock_release(address)

C#:

Annotate.LockRelease([int expr]);

// this C# argument is optional

Pause Collection and Resume Collection Annotations: lets you pause data collection to skip uninteresting code.

Pause Collection. The target program continues to execute.

C/C++:	`ANNOTATE_DISABLE_COLLECTION_PUSH;`
Fortran:	`call annotate_disable_collection_push()`
C#:	`Annotate.DisableCollectionPush();`

Resume Collection after it was stopped by a Pause Collection annotation.

C/C++:	`ANNOTATE_DISABLE_COLLECTION_POP;`
Fortran:	`call annotate_disable_collection_pop()`
C#:	`Annotate.DisableCollectionPop();`

Special-purpose Annotations: describe certain memory allocations to avoid false conflicts, disable reporting of problems or analysis, or enable reporting more detail for memory accesses. These apply only to the Dependencies tool. For their syntax, see the Special-purpose Annotations help topic.

Summary of Annotation Types

Note

See Also