Intel® Advisor User Guide

ID 766448
Date 11/07/2023
Public

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

Document Table of Contents

Special-purpose Annotations

All Intel Advisor special-purpose annotations are recognized by the Dependencies tool, which observes memory accesses in great detail. Some of these annotations prevent the Dependencies tool from reporting all or specific data sharing problems, while one (Observe Uses of Storage) provides more detail about memory accesses.

NOTE:

In the C/C++ syntax descriptions below, addresses and sizes are C++ expressions. Similarly, the Fortran var is a Fortran integer address.

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

This topic describes the following special-purpose annotations:

Inductive Expressions Uses

Induction variables (such as ++i) can often be eliminated when you add parallel framework code. Use this annotation to disable reporting data sharing problems for the specified memory region. This annotation is only recognized by the Dependencies tool.

Terminate this annotation with a Clear Uses of Storage annotation.

Syntax:

C/C++:

ANNOTATE_INDUCTION_USES(address, size);

Fortran:

call annotate_induction_uses(var)

C#:

Not supported

  • address is a C++ identifier or expression that provides information about the memory region for this annotation.

  • size is a C++ identifier or expression that provides information about the memory region for this annotation.

  • var is a Fortran integer address that provides information about the memory region for this annotation.

Reduction Uses

Reduction variables (such as sum += data[i]) can often be replaced with reduction operations when you add parallel framework code. Use this annotation to disable reporting data sharing problems for the specified memory region. This annotation is only recognized by the Dependencies tool.

Terminate this annotation with a Clear Uses of Storage annotation. For example, with C/C++ code:

 ANNOTATE_REDUCTION_USES(&sum, 4); 
    sum += a[i];
 ANNOTATE_CLEAR_USES(&sum); 

Syntax:

C/C++:

ANNOTATE_REDUCTION_USES(address, size);

Fortran:

call annotate_reduction_uses(var)

C#:

Not supported

  • address is a C++ identifier or expression that provides information about the memory region location for this annotation.

  • size is a C++ identifier or expression that provides information about the memory region location for this annotation.

  • var is a Fortran integer address that provides information about the memory region for this annotation.

Observe Uses of Storage

Use this annotation to report all accesses to the specified memory region. For example, this can help you find all of the uses of a variable to determine how you should refactor your code. This annotation gets reported as a Memory watch remark message in the Dependencies Report. This annotation is only recognized by the Dependencies tool.

NOTE:

For performance reasons, this annotation may not report memory access for variables stored on the stack.

To terminate this annotation, add a Clear Uses of Storage annotation.

Syntax:

C/C++:

ANNOTATE_OBSERVE_USES(address, size);

Fortran:

call annotate_observe_uses(var)

C#:

Not supported

  • address is a C++ expression that provides information about the memory region location for this annotation.

  • size is a C++ expression that provides information about the memory region location for this annotation.

  • var is a Fortran integer address that provides information about the memory region for this annotation.

Clear Uses of Storage

Use this annotation to terminate these annotations: Inductive Expressions Uses, Reduction Uses, and Observe Uses of Storage. For example, when the C/C++ ANNOTATE_CLEAR_USES(); annotation terminates ANNOTATE_OBSERVE_USES();, the Dependencies tool stops reporting all uses of the specified variable. This annotation is only recognized by the Dependencies tool.

Syntax:

C/C++:

ANNOTATE_CLEAR_USES(address);

Fortran:

call annotate_clear_uses(var)

C#:

Not supported

  • address is a C++ identifier or expression that provides information about the memory region location for this annotation.

  • var is a Fortran integer address that provides information about the memory region for this annotation.

Disable Observation Annotations

This annotation disables the reporting of problems until the matching Enable Observation Annotation is executed. After executing this annotation, the Dependencies tool does not report problems but continues to monitor other annotations so it can resume reporting problems if a matching Enable Observation Annotation is executed. This can be useful to suppress Dependencies problems that are false-positives or not useful in your program. Unlike ANNOTATE_CLEAR_USES; - which applies to a specific memory area - this annotation remains active until a disable-observation-pop annotation is executed to enable annotations. This annotation is only recognized by the Dependencies tool.

Syntax:

C/C++:

ANNOTATE_DISABLE_OBSERVATION_PUSH;

Fortran:

call annotate_disable_observation_push()

C#:

DisableObservationPush();

This annotation takes no arguments.

Enable Observation Annotations

This annotation enables the reporting of Dependencies stopped by a previous Disable Observation Annotation was executed to disable observation annotations. This annotation is only recognized by the Dependencies tool.

Syntax:

C/C++:

ANNOTATE_DISABLE_OBSERVATION_POP;

Fortran:

call annotate_disable_observation_pop()

C#:

Annotate.DisableObservationPop();

This annotation takes no arguments.

Memory Allocation Annotations

Memory allocation annotations apply only to C/C++ programs. They describe non-standard or user-defined memory allocations to avoid false conflicts reported by the Dependencies tool. Only use these Memory allocation annotations if you see false conflicts related to memory allocation in the Dependencies tool. This annotation is only recognized by the Dependencies tool.

Heap-allocated memory can be freed and then reused. If the same memory region is allocated during one task, then freed, and then re-allocated for use by a second task, this can confuse Dependencies tool analysis, because it appears as if two threads were accessing the same parallel memory region without synchronization. When the program runs in parallel runs in parallel, each thread could allocate different memory, so there is not really a data race.

The Dependencies tool understands the standard library memory allocation routines, such as malloc and free, operator new, and so on. However, if you have a user-defined memory allocator, the Dependencies tool may not accurately understand the memory relationships between different tasks. If your application utilizes a user-defined memory allocator, you may need to use these annotations to help the Dependencies tool understand the relationships. You place:

  • ANNOTATE_RECORD_ALLOCATION after a call to your non-standard or user-defined allocator.

  • ANNOTATE_RECORD_DEALLOCATION before the call to your non-standard or user-defined deallocator.

If you do not have such an allocator you can skip these annotations.

If you do have a user-defined memory allocator and you omit these annotations, you may see the effects as Memory reuse problems for the storage that is actually allocated by your allocator, and Data communication problems for the control information used by the allocator.

Syntax:

C/C++:

ANNOTATE_RECORD_ALLOCATION(address, size); and ANNOTATE_RECORD_DEALLOCATION(address);

Fortran:

Not supported

C#:

Not supported

ANNOTATE_RECORD_ALLOCATION(address, size); specifies the storage allocated by a user-memory allocator with a specific address and size:

  1. The address is a C++ expression that provides information about the memory region location for this annotation.

  2. The size is a C++ expression that provides information about the memory region size for this annotation.

Use ANNOTATE_RECORD_DEALLOCATION(address); each time your deallocator is freeing memory.

Static Loop Scheduling Annotations

Loop scheduling annotation inform the Suitability tool that the following loop will be divided into equal-sized (or as equal as possible) chunks. By default, chunk size is loop_count/number_of_threads.

Syntax:

C/C++:

ANNOTATE_AGGREGATE_TASK;

Fortran:

Not supported

C#:

Not supported