Developer Guide and Reference

Contents

Using Guided Auto Parallelism

The Guided Auto Parallelism feature of the Intel®
C++
Compiler is a tool offering selective advice to improve the performance of serially-coded applications. The tool suggests changes that take advantage of the compiler's ability to automatically vectorize and parallelize code as well as improve the efficiency of data operations. The tool does not require that you implement threaded code to improve the execution performance of your code, nor does it require that your code is already threaded or parallel code.
To invoke this tool, use the compiler option
[Q]guide
[=n]
. Using this option causes the compiler to generate messages suggesting ways to optimize the performance of your application. You can also use more specific compiler options such as
[Q]guide-vec
,
[Q]guide-par
, and
[Q]guide-data-trans
, to perform individual guided optimizations for vectorizing, parallelizing, and data transformation of your application.
When any guided auto parallelism option is used, the compiler provides only diagnostic advice. Object files or executables are not created in this mode. See the table below for descriptions of the options.
Syntax
Description
[Q]guide
Allows you to set a level of guidance for auto-vectorization and data transformation analysis.
To obtain guidance for auto parallelism, you must use the
[Q]parallel
option along with the
[Q]guide
option.
[Q]guide-par
Allows you to set a level of guidance only for auto parallelism analysis.
You must use the
[Q]parallel
option along with the
[Q]guide-par
option to get this advice.
[Q]guide-vec
Allows you to set a level of guidance for auto-vectorization analysis only.
[Q]guide-data-trans
Allows you to set a level of guidance for data transformation analysis only.
For all of the above options, the optional argument
n
specifies the level of guidance. The argument
n
takes the values
1-4
. When
n
is not specified, the default is
4
. If you specify
n=
1
or
2
, a standard level of guidance is provided.
When you use
n=
3
or
n=
4
, you may get advanced messages. For example, you may get messages about how to optimize a particular loop-nest or get a message on how exception-handling inside a loop-nest affects optimizations for that loop-nest. Or you may get a message on how to provide extra information to the compiler on cost-modeling (expected values of trip-counts, and so on).
If you simultaneously specify a level of guidance for the general
[Q]guide
option and also for one or more of the other specific guide options, the level of guidance (
n
) for the specific guide option overrides the general
[Q]guide
option setting.
If you do not specify a level of guidance for the general
[Q]guide
option, but do set a level of guidance for one or more of the specific guide options, the
[Q]guide
option is set equal to the greatest value passed to the specific guide options.

Capturing Guidance Messages

The guided auto parallelism tool analyzes all of your serial code or individual parts of your code and generates advisory messages. By default, messages that are generated by the guided auto parallelism tool are output to
stderr
.
To capture messages in a file, use the options listed in the following table.
The options listed in the following table must be used with the
[Q]guide
,
[Q]guide-par
,
[Q]guide-vec
, or
[Q]guide-data-trans
options. If not, they are ignored.
Syntax
Description
[Q]guide-file
Gathers all messages generated during a guided auto-parallelization run into the specified file.
[Q]guide-file-append
Allows you to specify the file into which all messages generated during a guided auto parallelism run should be appended.
For the above options, the
file_name
argument can also include a path. If a path is not specified, the file is created in the current working directory. If there is already a file named
file_name
, it is overwritten when you use the
[Q]guide-file
option. If you do not include an extension as part of the
file_name
, the extension
.guide
is appended.

Configuring Code Regions for GAP Messages

To limit guided auto parallelism analysis to specific regions (hotspots) in your application, use the option mentioned in the table below.
Syntax
Description
[Q]guide-opts
Allows you to analyze specified code elements, identified by
string
.
You must use the
[Q]guide-opts
option along with one of the guided auto parallelism options, such as
[Q]guide
,
[Q]guide-vec
,
[Q]guide-par
, and
[Q]guide-data-trans
. Use the
string
parameter to provide information about known areas of interest (hotspots). The
string
parameter takes one or more of the following variables:
filename
,
routine
,
range
. The compiler parses the
string
parameter and generates syntax errors if there are any.
Windows* Syntax
/Qguide-opts
:
string
Linux* and
macOS*
Syntax
-guide-opts
=
string
Follow these guidelines when using the
string
parameter:
  • Use only valid file names, routine names, and line numbers. The guided auto parallelism tool ignores invalid values and issues a diagnostic message stating what was ignored.
  • Enclose routine names within single quotation marks. Specify original source names (demangled names) as routine names. A routine name alone may not always be sufficient to uniquely identify a routine. You may need to specify additional parameter information to uniquely identify the routine.
    For example:
    Linux* and
    macOS*
    :
    -guide-opts="foo.cpp,'CLHEP::StaticRandomSta::restore(std::basic_istream<char,std::char_traits<char>>&)'" -guide-opts="bar.f90,'module_1::routine_name`" -guide-opts="baz.c,'c_routine_name'"
    Windows*:
    /Qguide-opts:"foo.cpp,'CLHEP::StaticRandomSta::restore(std::basic_istream<char,std::char_traits<char>>&)'" /Qguide-opts:"bar.f90,'module_1::routine_name`" /Qguide-opts:"baz.c,'c_routine_name'"
    For any specified routine name, the GAP tool first tries to uniquely identify the routine using specified routine information. If that is not possible, then it selects all routines with the specified routine name. The GAP tool uses the parameter information, if specified, to narrow the selection.
  • When inlining is involved, use the callee line numbers. The generated messages also use the callee line numbers.