# annotation TargetFeature

##
Overview

The annotation allows to assume special CPU model/features for a method.

It is similar to the `--cpu` and `--mattr` build arguments, but where the scope is limited to the annotated `def` or `fun`. It allows to compile a single executable, yet allow some optimized functions that will only run when available, such as specific SIMD instructions for example.

CPU feature and model selections only accept values valid for the current target platform architecture.

It is a semantic error to call a method with a feature requirement that is invalid for the current target architecture. Calls typically require macro guard clauses on top of runtime feature tests.

For example:

    {% if flag?(:x86_64) %}
      @[TargetFeature("+avx2")]
      private def foo_avx2
      end

      private def cpu_supports_avx2?
      end
    {% end %}

    private def foo_portable
    end

    def foo
      {% if flag?(:x86_64) %}
        return foo_avx2 if cpu_supports_avx2?
      {% end %}
      foo_portable
    end

WARNING When a method has been compiled with a feature and that feature is not supported at runtime, calling this method will result in an illegal instruction, and is undefined behaviour.

##
Defined in:

annotations.cr