Annotations typically expand to calls to one or more functions, with minimal additional code. When you run the Suitability or Dependencies tools, the calls are instrumented during data collection.
Most annotations must be used in pairs that will execute in a begin-end sequence, such as the parallel site annotations for a site with a single task:
Any mismatched annotations show up as error during data collection.
For example, if your C/C++ code has an
that is executed, but no corresponding
, you will see a message, such as:
Error: Missing end site
when you run the Suitability or Dependencies tool.
You can also use annotations when they are dynamically paired. This lets you annotate code regions that might have more than one exit point. For example, consider this parallel site with multiple tasks:
//Show that an end task annotation should be repeated for a jump out of a loop
ANNOTATE_TASK_END(); // unreachable!
With C/C++, when you add annotations after a loop that executes only one statement without opening and closing braces (
), add opening and closing braces to allow multi-statement execution of both the original statement and the added annotation statement.
From a program source perspective, the annotation macros expand as a single executable statement (or to nothing if null expansion is used). This allows annotations to be used in locations requiring a single statement safely, as in this example: