[PATCH] [DOC] Documentation for pragma optimize on/off

[Dario Domizioli]

Hi Aaron.

On 23 May 2014 16:50, Aaron Ballman <aaron at aaronballman.com> wrote:

> Of course, I went and looked *after* I sent the email, but optnone is
> documented.
> ...
> However, we're currently experiencing difficulties with the
> server-side process that converts this into live documentation, so
> that documentation is not live yet. I've brought this up with the
> server admin, and will continue to follow up until it's resolved.
>

I see.
I think the best option would then be to have a link to the attribute
documentation from the language extensions document, but I seem to
understand that at the moment we don't have that possibility. We can always
add the link later, though.

Meanwhile, I'm attaching a revised documentation patch, which provides a
bit more detail on the effects of the pragma (especially with templates)
and mentions the fact that a missing "on" means that the "off" region
extends up to the end of the compilation unit.

Cheers,
    Dario Domizioli
    SN Systems - Sony Computer Entertainment Group
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140527/0cc4c5ae/attachment.html>
-------------- next part --------------
Index: docs/LanguageExtensions.rst
===================================================================
--- docs/LanguageExtensions.rst	(revision 209650)
+++ docs/LanguageExtensions.rst	(working copy)
@@ -1667,3 +1667,82 @@
 
 Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
 with :doc:`MemorySanitizer`.
+
+
+Extensions for selectively disabling optimization
+=================================================
+
+Clang provides a mechanism for selectively disabling optimizations in functions
+and methods.
+
+To disable optimizations in a single function definition, the GNU-style or C++11
+non-standard attribute ``optnone`` can be used.
+
+.. code-block:: c++
+
+  // The following functions will not be optimized.
+  // GNU-style attribute
+  __attribute__((optnone)) int foo() {
+    // ... code
+  }
+  // C++11 attribute
+  [[clang::optnone]] int bar() {
+    // ... code
+  }
+
+To facilitate disabling optimization for a range of function definitions, a
+range-based pragma is provided. Its syntax is ``#pragma clang optimize``
+followed by ``off`` or ``on``.
+
+All function definitions in the region between an ``off`` and the following
+``on`` will be decorated with the ``optnone`` attribute unless doing so would
+conflict with explicit attributes already present on the function (e.g. the
+ones that control inlining).
+
+.. code-block:: c++
+
+  #pragma clang optimize off
+  // This function will be decorated with optnone.
+  int foo() {
+    // ... code
+  }
+
+  // optnone conflicts with always_inline, so bar() will not be decorated.
+  __attribute__((always_inline)) int bar() {
+    // ... code
+  }
+  #pragma clang optimize on
+
+If no ``on`` is found to close an ``off`` region, the end of the region is the
+end of the compilation unit.
+
+Note that a stray ``#pragma clang optimize on`` does not selectively enable
+additional optimizations when compiling at low optimization levels. This feature
+can only be used to selectively disable optimizations.
+
+The pragma has an effect on functions only at the point of their definition; for
+function templates, this means that the state of the pragma at the point of an
+instantiation is not necessarily relevant. Consider the following example:
+
+.. code-block:: c++
+
+  template<typename T> T twice(T t) {
+    return 2 * t;
+  }
+
+  #pragma clang optimize off
+  template<typename T> T thrice(T t) {
+    return 3 * t;
+  }
+
+  int container(int a, int b) {
+    return twice(a) + thrice(b);
+  }
+  #pragma clang optimize on
+
+In this example, the definition of the template function ``twice`` is outside
+the pragma region, whereas the definition of ``thrice`` is inside the region.
+The ``container`` function is also in the region and will not be optimized, but
+it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of
+these two instantiations, ``twice`` will be optimized (because its definition
+was outside the region) and ``thrice`` will not be optimized.