Intel® C++ Compiler Classic Developer Guide and Reference

ID 767249
Date 12/16/2022
Public

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

Document Table of 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.

NOTE:

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.

NOTE:

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.