intro_directives

Date:: 07-30-2026

NAME

intro_directives - Introduction to Cray Fortran Compiler directives

DESCRIPTION

Directives are instructions that may be inserted into source code in order to specify certain kinds of special processing to be performed by the compiler during compilation. Directives are not Fortran statements.

This man page provides a high-level overview of how directives are used in the Cray Fortran Compiler. A short description of each directive is given at the end of this man page. For specific information about using a particular directive, see the appropriate man page for that directive.

The directives are classified according to the following types:

General
Vectorization
Scalar
Inlining
PGAS

Using Directives: Cray Fortran Compiler

A directive line begins with the characters CDIR$ or !DIR$. How you specify a directive depends on the source form you are using.

If you are using fixed source form, indicate a directive line by placing CDIR$ or !DIR$ in columns 1 through 5. If the compiler encounters a non-blank character is column 6, the line is assumed to be a directive continuation line. Columns 7 and beyond can contain one or more directives. Characters entered in columns beyond the default column width are ignored.
If you are using free source form, indicate a directive by placing !DIR$, followed by a space, then one or more directives. If the position following the !DIR$ contains a character other than a blank, tab, or newline character, the line is assumed to be a continuation line. For example, the asterisk (*) in column 6 on the second line indicates that it is a continuation of the first line:

!DIR$ Nosideeffects
!DIR$*ab

The !DIR$ need not start in column 1, but it must be the first text on the line.
The FIXED and FREE directives must appear alone on a directive line and cannot be continued.
Do not use source preprocessor (#) directives within multiline compiler directives.

If you want to specify more than one directive on a line, separate each directive with a comma. Some directives require that you specify one or more arguments; when specifying a directive of this type, no other directive can appear on the line.

Spaces can precede, follow, or be embedded with a directive, regardless of the source form.

Scope

At the beginning of each section that describes a directive, information is included about the scope of the directive. Unless otherwise noted, the following default scope applies to each directive:

Scope:: Local and global

Range and Placement of Directives

FIXED and FREE directives can appear anywhere in your source code. All other directives must appear within a program unit.

The following directives must be placed in the declarative portion of a program unit and apply only to that program unit: CACHE, CACHE_NT, COPY_ASSUMED_SHAPE, IGNORE_TKR, MEMORY, NAME, NOSIDEEFFECTS, SAME_TBS, STACK, and WEAK.

The following directives toggle a compiler feature on or off at the point at which the directive appears in the code. These directives remain in effect until the opposite directive appears, until the directive is reset, or until the end of the program unit, at which time the command line settings become the default for the remainder of the compilation: [NO]AUTOTHREAD,[NO]BOUNDS, [NO]CLONE, [NO]COLLAPSE, [NO]FUSION, [NO]INLINE, [NO]PATTERN, [NO]PIPELINE, [NO]UNROLL, [NO]VECTOR.

RESET CLONE and RESET INLINE apply at the point at which they appear and set cloning or inlining back to the default.

The SUPPRESS directive applies at the point at which it appears.

The ID directive does not apply to any particular range of code. It adds information to the .o file generated from the source.

The following directives apply only to the next loop or block of code encountered lexically: BLOCKABLE, BLOCKINGSIZE|NOBLOCKING, CONCURRENT, HAND_TUNED, [NO]INTERCHANGE, IVDEP, NEXTSCALAR, NOFISSION, PERMUTATION, PREFERVECTOR, PROBABILITY, SAFE_ADDRESS, SAFE_CONDITIONAL, LOOP_INFO.

The following directives alter the status of entities in ways that affect compilation. They do not apply to particular ranges of code: IGNORE_TKR, INLINEALWAYS|INLINENEVER, CLONEALWAYS|CLONENEVER, NAME, NOSIDEEFFECTS.

The [NO]MODINLINE directives are in effect for the scope of the program unit in which they are specified, including all contained procedures. If one of these directives is specified in a contained procedure, the contained procedure’s directive overrides the containing procedure’s directive.

Interaction with the crayftn Command Line

Note the following interactions between directives and crayftn command line options.

-x               The -x option accepts one or more directives as
                 arguments. Directives specified with the -x option
                 are ignored during compilation. To ignore all
                 compiler directives, specify -x all.

-O 0             The -O 0 option disables all compiler
                 optimizations. All scalar optimization,
                 vectorization, and tasking directives are
                 ignored.

-O ipaN          The -O ipa0 option disables all inlining and
                 cloning optimizations. All inlining and
                 cloning directives are ignored.

-O scalar0       The -O scalar0 option disables all scalar
                 optimizations. All scalar optimization and
                 vectorization directives are ignored.

-O vector0       The -O vector0 option disables vectorization.
                 All vectorization directives are ignored.

Cray Fortran Compiler Directives Man Pages

The following tables list the directives supported by the Cray Fortran compiler. See the individual directive’s man page for more information about the use and effect of the directive.

                      Table 1. General Directives

[NO]AUTOTHREAD                     Turn autothreading on and off for
                                   selected blocks of code.
BLOCKABLE                          Specifies that it is legal to cache
                                   block the subsequent loops.
BLOCKINGSIZE                       Assert that the loop following the
                                   directive either is or is not
                                   involved in a cache blocking.
[NO]BOUNDS                         Specifies that pointer and array
                                   references are to be checked/not
                                   checked.
CACHE                              Asserts that all memory operations
                                   with the specified symbols as the
                                   base are to be allocated in cache.
CACHE_NT                           Specifies objects that should use
                                   non-temporal reads and writes.
                                   Advisory.
NAME                               Provides additional, externally
                                   visible names for specified
                                   subprograms.
FREE, FIXED                        Specify if the source code uses the
                                   free or fixed format.
[NO]FUSION                         Direct the compiler to attempt or not
                                   attempt loop fusion on the following
                                   loop.
ID                                 Directs the compiler to store the
                                   string indicated by text into the
                                   object (.o) file.
IGNORE_TKR                         Ignore the type, kind, and rank of
                                   specified dummy arguments.
MEMORY                             Place heap-allocations or variables
                                   in specific types of memory. This is
                                   intended for use only on systems that
                                   support more than one type of
                                   explicitly addressable on-node
                                   memory: for example, systems having
                                   both normal DDR memory and high-
                                   bandwidth MCDRAM memory.
OPTIMIZE                           Enable optimization in the program
                                   unit in which it appears, overriding
                                   the optimization level set via the
                                   compiler command line.
PREFETCH                           Directs the compiler to prefetch a
                                   variable or array element from local
                                   memory into cache prior to a
                                   reference or to store a value into
                                   cache prior to a local memory write.
PREPROCESS                         Allow an include file to be
                                   preprocessed.
PROBABILITY,                       Specify information used by
PROBABILITY_ALMOST_ALWAYS,         interprocedure analysis (IPA) and the
PROBABILITY_ALMOST_NEVER           optimizer to produce faster code
                                   sequences. The specified probability
                                   is a hint, rather than a statement of
                                   fact.
STACK                              Allocate storage to the stack in the
                                   program unit containing the
                                   directive.
WEAK                               Specifies an external identifier that
                                   may remain unresolved throughout the
                                   compilation.

                   Table 2. Vectorization Directives

COPY_ASSUMED_SHAPE                 Copy assumed-shape dummy array
                                   arguments into contiguous local
                                   temporary storage.
HAND_TUNED                         Asserts that the code in the loop
                                   nest has been arranged by hand for
                                   maximum performance, and the compiler
                                   should restrict some of the more
                                   aggressive automatic expression
                                   rewrites.
IVDEP                              Ignore vector dependencies, including
                                   explicit dependencies, when
                                   attempting to vectorize the first
                                   loop that follows the directive.
LOOP_INFO                          Allows additional information to be
                                   specified about the behavior of a
                                   loop, including run time trip count
                                   and hints on cache allocation
                                   strategy.
LOOP_INFO PREFER_THREAD,           Indicate a preference for turning
LOOP_INFO PREFER_NOTHREAD          threading on or off for selected
                                   loops.
NEXTSCALAR                         Disable vectorization for the first
                                   DO or DO WHILE loop following the
                                   directive.
[NO]PATTERN                        Disables pattern matching for the
                                   loop immediately following the
                                   directive.
PERMUTATION                        Specifies that an integer array has
                                   no repeated values.
[NO]PIPELINE                       Enables/disables the compiler
                                   analysis of all vector loops and its
                                   automatic attempt to pipeline a loop
                                   if doing so can be expected to
                                   produce a significant performance
                                   gain.
PREFERVECTOR                       Directs the compiler to vectorize the
                                   loop immediately following the
                                   directive if the loop contains more
                                   than one loop in the nest that can be
                                   vectorized.
SAFE_ADDRESS                       Specifies that it is safe to
                                   speculatively execute memory
                                   references within all conditional
                                   branches of a loop.
SAFE_CONDITIONAL                   Specifies that it is safe to execute
                                   all references and operations within
                                   all conditional branches of a loop.
SAME_TBS                           Specifies that assumed shape array
                                   arguments are of same type, bounds,
                                   and stride allowing more efficient
                                   code.
[NO]VECTOR                         Controls vectorization of DO loops.
                                   May affect specific optimizations.

                       Table 3. Scalar Directives

[NO]COLLAPSE                       Controls collapse of the immediately
                                   following loop nest.
CONCURRENT                         Indicates that no data dependence
                                   exists between array references in
                                   different iterations of the loop that
                                   follows the directive.
[NO]INTERCHANGE                    Specifies whether or not the order of
                                   the following two or more loops
                                   should be interchanged.
SUPPRESS                           Suppresses optimization determined by
                                   its use with global or local scope.
[NO]UNROLL                         Control unrolling for individual
                                   loops or specifies no unrolling of a
                                   loop.
[NO]FUSION                         Instructs the compiler to attempt/not
                                   attempt loop fusion on the following
                                   loop.
NOFISSION                          Instructs the compiler not to split
                                   the following loop. Fission is
                                   prevented only for the loop level
                                   specified; loops nested within the
                                   specified loop remain candidates for
                                   fission.
NOSIDEEFFECTS                      Declare that a called subprogram does
                                   not redefine selected variables.

                Table 4. Inlining and Cloning Directives

[NO]CLONE, RESETCLONE              Control whether cloning is attempted
                                   over a range of code. The RESETCLONE
                                   directive returns the cloning state
                                   to the state specified on the
                                   compiler command line.
CLONEALWAYS, CLONENEVER            The CLONEALWAYS directive identifies
                                   subprograms that the compiler should
                                   always attempt to clone. The
                                   CLONENEVER directive identifies
                                   subprograms that are never to be
                                   cloned.
[NO]INLINE, RESETINLINE            The INLINE directive tells the
                                   compiler to attempt to inline
                                   subprograms at call sites. The
                                   NOINLINE directive tells the compiler
                                   to not inline subprograms at call
                                   sites. The RESETINLINE directive
                                   returns the inlining state to the
                                   state specified on the command line
                                   (-h ipan).
INLINEALWAYS, INLINENEVER          The INLINEALWAYS directive identifies
                                   subprograms that the compiler should
                                   always attempt to inline. The
                                   INLINENEVER directive identifies
                                   subprograms that are never to be
                                   inlined.
[NO]MODINLINE                      Enable or disable the creation of
                                   inlineable templates for specific
                                   module procedures.

                        Table 5. PGAS Directives

PGAS BUFFERED_ASYNC                Batch PGAS operations into buffers to
                                   be processed in bulk. No ordering
                                   guarantees are made until the next
                                   fence instruction. Fences provide
                                   ordering and visibility guarantees
                                   for BA operations.
PGAS DEFER_SYNC                    Defer the synchronization of PGAS
                                   data until the next fence
                                   instruction.