User Guide

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.
In the C/C++ syntax descriptions below,
addresses
and
sizes
are C++ expressions. Similarly, the Fortran
var
is a Fortran integer address.
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.
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

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804