ARB compiles with vectorization (enabled by -O3 in NDEBUG or RELEASE mode).
The vectorization check is automatically activated for gcc versions >= 4.9.0
Compiler output of earlier versions is not suitable for automated checks.

To ensure that code does not degrade (i.e. does not fail to vectorize), the
compiler output is searched for successful vectorizations and the result is
checked against special comments in code.

Currently there are 2 types of comments for vectorization-checks:

        IRRELEVANT_LOOP
        LOOP_VECTORIZED[<count>][<exclusions>]

Use IRRELEVANT_LOOP to mark a loop where vectorization occurs (maybe only
sometimes) and where it isn't mandatory. No error or warning will show if
vectorization fails.

Note: You have to use IRRELEVANT_LOOP for conditional code (e.g. unittest code)


Use LOOP_VECTORIZED for loops that SHALL get vectorized (i.e. loops with
relevant impact on performance). If vectorization fails for a loop commented
with LOOP_VECTORIZED, compilation will fail with an error.

  The optional argument <count> allows to specify the amount of performed
  vectorizations. This is relevant if the loop is part of a template, gets
  vectorized multiple times and it shall be ensured that the vectorizations
  happens for each instanciation of that template.

    The syntax of the <count> argument is "=<num>" or "=*". The first form
    expects that <num> vectorizations occur. The second form allows any number
    of vectorizations (1 to many). The default for <count> is "=1".

  The 2nd optional argument <exclusions> allows to exclude compiler versions
  that fail to vectorize that loop.

    The syntax is "["<excl>[","<excl>]*"]".
    <excl> may have any of the following forms:

        "!"  <version>          exclude specified version
        "!<" <version>          exclude all versions BEFORE specified version
        "!>" <version>          exclude all versions AFTER  specified version
        "!<="<version>          exclude all versions UNTIL  specified version
        "!>="<version>          exclude all versions SINCE  specified version

    <version> is a specific compiler version (e.g. "4.9.3" or "493" or "5").

    Multiple conditions can be specified in one <excl>, e.g. "!>=5<7" excludes
    all compilers of 5.x and 6.x series.

    Example: // LOOP_VECTORIZED[!493,!531]
    => expects vectorization occurs for all compiler versions but 4.9.3 and 5.3.1

Included code:

  Vectorization checks do not work very well with included code (e.g. inline
  code from headers): IRRELEVANT_LOOP behaves normal, but LOOP_VECTORIZED may
  differ for different includers. 'LOOP_VECTORIZED=*' might work, but is not
  recommended, because if code starts to fail vectorization, no warning will
  show up! If possible better move code from header into source.

Recompilation needed for complete check:

  To force a complete check of expected vectorizations call target
  'clean_checked_vect' before build! Previous failures (only) in
  vectorization-check will not delete the generated object file, i.e. w/o
  change of the affected source file no re-compilation will happen.

Alternative ways to use vectorization checker:

  Set ../Makefile@TRACE_MISSED_VECTORIZATIONS
  to 1 to dump details about performed and failed vectorizations.

  Set ../Makefile@VECTORIZATION_CHECK_CANDIDATES
  to 1 to dump candidates from unchecked files.

Related stuff:

  If you encounter problems caused by vectorization, you may use
  ../TEMPLATES/attributes.h@__ATTR__DONT_VECTORIZE

Some pointers (if you need to adapt vectorization checking):

  - global vectorization toggles:
       ../Makefile@DISABLE_VECTORIZE_CHECK
                    (automatically disabled if sanitizer enabled)
       ../Makefile@TRACE_MISSED_VECTORIZATIONS
       ../Makefile@VECTORIZATION_CHECK_CANDIDATES

  - the build maintains a list of source-files to be checked using
    target 'vectorize_checks' (called via target 'depends').
    The list is stored in ./vectorized.source
    and is generated by ./Makefile@vectorize_checks

  - the actual check is performed by ./postcompile.pl