<h1>Range-based optnone spec</h1>

<h2>Introduction and motivation</h2>

<p>Attribute <code>optnone</code> has been introduced to provide a way to selectively disable
most optimizations for each function marked with the attribute.</p>

<p>Disabling optimizations for multiple functions requires specifying attribute
<code>optnone</code> on the definitions of all those functions. An easier approach from a
user's point of view would be to specify regions of code within which all
functions are automatically marked with the <code>optnone</code> attribute.</p>

<p>The goal of this feature would be to behave in a similar way to "#pragma
optimize off" in Visual Studio, or "#pragma GCC optimize (0)" in gcc.</p>

<p>This document describes a tentative specification for such functionality and
provides a rationale for said specification, while listing some examples to give
an overview of typical usage and possible edge cases.</p>

<h2><code>pragma optnone</code> specification</h2>

<p>The compiler shall provide a new <code>#pragma</code> directive in the <code>clang</code> namespace,
whose name shall be <code>optnone</code>.</p>

<h3>Syntax</h3>

<p>The <code>#pragma clang optnone on</code> directive shall mark the
beginning of a region affected by the region-based optnone functionality; the
end of said region shall be the next following <code>#pragma clang optnone off</code>
directive or the end of the compilation unit if no "off" directive is present.</p>

<pre><code>// Start of source file

// ... normal code ...

#pragma clang optnone on

// ... more code - region affected by optnone

#pragma clang optnone off

// ... more normal code...

#pragma clang optnone on

// ... more code - region affected by optnone

// End of file
</code></pre>

<p>A stray <code>#pragma clang optnone off</code> shall produce a
warning but shall not have any other effect.</p>

<pre><code>// Start of source file

// ... normal code ...

#pragma clang optnone off // WARNING! 

// ... more normal code
</code></pre>

<p>A <code>#pragma clang optnone</code> directive (either on or
off) shall only be present at module, namespace or class level. It shall be an
error if such a directive is encountered in the body of a function or method.</p>

<pre><code>// ... code ...

int foo(int a, int b) {
    #pragma clang optnone on   // ERROR!
    return bar(a) + bar(b);
    #pragma clang optnone off  // ERROR!
}

// ... code ...
</code></pre>

<h3>Semantics</h3>

<p>Any and all function or method definitions that fall
within a region affected by the range-based optnone functionality after
preprocessor expansion shall be considered by the compiler as decorated with the
<code>optnone</code> attribute, but only if said attribute would not conflict with explicit
attributes already present on the function. No diagnostic is required if such
conflicts are encountered.</p>

<p>[ <em>Note:</em> for example, <code>always_inline</code> is an attribute that conflicts with
<code>optnone</code> and therefore <code>always_inline</code> functions in the region would not be
decorated with an additional <code>optnone</code> attribute. - <em>end note</em> ]</p>

<pre><code>#pragma clang optnone on

// This is a macro definition and therefore its text is not present after
// preprocessing. The pragma has no effect here.
#define CREATE_FUNC(name)        \
int name (int param) {           \
    return param;                \
}                                \

// This is a declaration and therefore it is not decorated with `optnone`.
extern int foo(int a, int b);

// This is a definition and therefore it will be decorated with `optnone`.
int bar(int x, int y) {
    for(int i = 0; i < x; ++i)
        y += x;
    return y;
}

// The function "int created (int param)" created by the macro invocation
// is also decorated with the `optnone` attribute because it is within a
// region of code affected by the functionality (not because of the position
// of the macro definition).
CREATE_FUNC (created)

class MyClass {
    public:
        // The declaration of the method is not decorated with `optnone`.
        int method(int blah);
};

// The definition of the method instead is decorated with `optnone`.
int MyClass::method(int blah) {
    return blah + 1;
}

// A template declaration will not be decorated with `optnone`.
template <typename T> T twice (T param);

// The template definition will be decorated with the attribute `optnone`.
template <typename T> T thrice (T param) {
    return 3 * param;
}

// This function definition will not be decorated with `optnone` because the
// attribute would conflict with `always_inline`.
int __attribute__((always_inline)) baz(int z) {
    return foo(z, 2);
}

#pragma clang optnone off

// The function "int wombat(int param)" created by the macro is not
// decorated with `optnone`, because the pragma applies its effects only
// after preprocessing. The position of the macro definition is not
// relevant.
CREATE_FUNC (wombat)


// This instantiation of the "twice" template function with a "float" type
// will not have an `optnone` attribute because the template declaration was
// not affected by the pragma.
float container (float par) {
    return twice(par);
}

// This instantiation of the "thrice" template function with a "float" type
// will have an `optnone` attribute because the template definition was
// affected by the pragma.
float container2 (float par) {
    return thrice(par);
}


// A template specialization is a new definition and it will not be
// decorated with an `optnone` attribute because it is now outside of the
// affected region.
template<> int thrice(int par) {
    return (par << 1) + par;
}
</code></pre>

<h2><code>pragma optnone</code> rationale</h2>

<h3>Syntax rationale</h3>

<p>The rationale behind a <code>on/off</code> approach is as follows.</p>

<p>First of all, it does not make sense for the semantics of the functionality to
maintain a stack of values, because the values in the stack would just be
booleans. So a <code>push/pop</code> approach is not really needed.</p>

<p>Secondly, it is envisaged that even if using an <code>on/off</code> terminology could be
confusing for the user because of the double negative (does "optnone off" really
mean optimizations are back on?) it is easy enough to understand once the user
has used it once or twice.</p>

<p>It is envisaged that if we ever have a full "pragma optimize" functionality, the
"pragma optnone" functionality will probably become obsolete, but it will still
work independently and its implementation decisions will not affect any future
development on "pragma optimize".</p>

<p>Because the <code>optnone</code> automated decoration is designed to imitate Visual
Studio's "pragma optimize" or GCC's "pragma GCC optmize", there is no
requirement on nested or repeated directives. The additional warning for a stray
"off" directive is just for information.</p>

<h3>Semantics rationale</h3>

<p>The semantics for the basic use cases should be as simple as possible - and they
are. Anything within a "pragma optnone" region has the <code>optnone</code> attribute if it
can be applied to it. It is easy to understand.</p>

<p>Macros however are dealt with by the preprocessor. In order to apply the pragma
to function declarations within macros it would be necessary to make the pragma
functionality understand and parse the replacement text of the macro, a
complication that is deemed not justified for any realistic use case.</p>

<p>Note that the desired effect can still be obtained by enclosing the macro
<em>instantiations</em> in a "pragma optnone" region.</p>

<p>Templates and classes are instead constructs of the C++ language. It is
envisaged that the parser can recognize and automatically decorate any
definition of functions and methods in those constructs.</p>