Recommend #pragma once for self-iteration

doc/topics/file_iteration.html

@@ -197,13 +197,18 @@ <h4>
    #ifndef SAMPLE_H
    #define SAMPLE_H
 
+   #include &lt;boost/config.hpp&gt; // BOOST_HAS_PRAGMA_ONCE
    #include &lt;boost/preprocessor/iteration/iterate.hpp&gt;
 
    template&lt;int&gt; struct sample;
 
    #define BOOST_PP_ITERATION_PARAMS_1 (3, (1, 5, "sample.h"))
    ??=include BOOST_PP_ITERATE()
 
+   #ifndef BOOST_HAS_PRAGMA_ONCE
+      #pragma once
+   #endif
+
    #endif // SAMPLE_H
 
 #else
@@ -213,6 +218,17 @@ <h4>
 #endif
 </pre>
 		</div>
+		<div>
+			Although not necessary for correctness, <code>#pragma once</code> is
+			added after <b>BOOST_PP_ITERATE</b> to trigger the <i>multiple-include
+			optimization</i>, allowing compilers to avoid subsequent includes of
+			"sample.h" to improve build speed. In this instance the the include guard
+			is not sufficient to trigger the multiple-include optimization as is it not
+			the first preprocessor directive occurring in the file.
+			<code>#pragma once</code> must occur <i>after the last top-level</i>
+			<b>BOOST_PP_ITERATE()</b>, after which "sample.h" will no longer
+			self-include.
+		</div>
 		<div>
 			Using the same file like this raises another issue.&nbsp; What happens when a 
 			file performs two separate file iterations over itself?&nbsp; This is the 
@@ -227,6 +243,7 @@ <h4>
    #ifndef SAMPLE_H
    #define SAMPLE_H
 
+   #include &lt;boost/config.hpp&gt; // BOOST_HAS_PRAGMA_ONCE
    #include &lt;boost/preprocessor/iteration/iterate.hpp&gt;
    #include &lt;boost/preprocessor/repetition/enum_params.hpp&gt;
    #include &lt;boost/preprocessor/repetition/enum_shifted_params.hpp&gt;
@@ -257,6 +274,10 @@ <h4>
    #define BOOST_PP_ITERATION_PARAMS_1 (4, (2, TYPELIST_MAX, "sample.h", 2))
    ??=include BOOST_PP_ITERATE()
 
+   #ifndef BOOST_HAS_PRAGMA_ONCE
+      #pragma once
+   #endif
+
    #endif // SAMPLE_H
 
 #elif BOOST_PP_ITERATION_FLAGS() == 1
@@ -331,6 +352,10 @@ <h4>
    #define BOOST_PP_ITERATION_PARAMS_1 (3, (1, EXTRACT_MAX, "extract.h"))
    ??=include BOOST_PP_ITERATE()
 
+   #ifndef BOOST_HAS_PRAGMA_ONCE
+      #pragma once
+   #endif
+
    #endif // EXTRACT_H
 
 #else
@@ -460,6 +485,10 @@ <h4>
    #define BOOST_PP_ITERATION_PARAMS_1 (3, (1, 2, "file.h"))
    ??=include BOOST_PP_ITERATE()
 
+   #ifndef BOOST_HAS_PRAGMA_ONCE
+      #pragma once
+   #endif
+
    #endif // FILE_H
 
 #elif BOOST_PP_ITERATION_DEPTH() == 1
@@ -666,6 +695,10 @@ <h4>
 
    ??=include BOOST_PP_ITERATE()
 
+   #ifndef BOOST_HAS_PRAGMA_ONCE
+      #pragma once
+   #endif
+
 #endif // FILE_H
 
 #else
@@ -938,6 +971,10 @@ <h4>
       ??=include BOOST_PP_INCLUDE_SELF()
    #endif
 
+   #ifndef BOOST_HAS_PRAGMA_ONCE
+      #pragma once
+   #endif
+
 // iteration over cv-qualifiers
 #elif BOOST_PP_ITERATION_DEPTH() == 1 \
    &amp;&amp; BOOST_PP_ITERATION_FLAGS() == 1 \

test/iteration.h

@@ -11,6 +11,8 @@
 #
 # if !BOOST_PP_IS_ITERATING
 #
+# include <boost/config.hpp>
+#
 # include <boost/preprocessor/cat.hpp>
 # include <boost/preprocessor/comparison/equal.hpp>
 # include <boost/preprocessor/control/expr_iif.hpp>
@@ -177,6 +179,10 @@
 #
 # undef ITER50SA
 #
+# ifndef BOOST_HAS_PRAGMA_ONCE
+# pragma once
+# endif
+#
 # endif
 #
 # else