[NaCl SDK Docs] Check in the generated NaCl SDK Documentation.

native_client_sdk/src/doc/_developer.chrome.com_generated/reference/pnacl-c-cpp-language-support.html

Index: native_client_sdk/src/doc/_developer.chrome.com_generated/reference/pnacl-c-cpp-language-support.html
diff --git a/native_client_sdk/src/doc/_developer.chrome.com_generated/reference/pnacl-c-cpp-language-support.html b/native_client_sdk/src/doc/_developer.chrome.com_generated/reference/pnacl-c-cpp-language-support.html
new file mode 100644
index 0000000000000000000000000000000000000000..4179c94f11ddcb7f171652774095f026b10662f5
--- /dev/null
+++ b/native_client_sdk/src/doc/_developer.chrome.com_generated/reference/pnacl-c-cpp-language-support.html
@@ -0,0 +1,216 @@
+{{+bindTo:partials.standard_nacl_article}}
+
+<section id="pnacl-c-c-language-support">
+<h1 id="pnacl-c-c-language-support">PNaCl C/C++ Language Support</h1>
+<div class="contents local topic" id="contents">
+<ul class="small-gap">
+<li><p class="first"><a class="reference internal" href="#source-language-support" id="id2">Source language support</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#preprocessor-definitions" id="id3">Preprocessor definitions</a></li>
+</ul>
+</li>
+<li><p class="first"><a class="reference internal" href="#memory-model-and-atomics" id="id4">Memory Model and Atomics</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#memory-model-for-concurrent-operations" id="id5">Memory Model for Concurrent Operations</a></li>
+<li><a class="reference internal" href="#atomic-memory-ordering-constraints" id="id6">Atomic Memory Ordering Constraints</a></li>
+<li><a class="reference internal" href="#volatile-memory-accesses" id="id7">Volatile Memory Accesses</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#threading" id="id8">Threading</a></li>
+<li><a class="reference internal" href="#setjmp-and-longjmp" id="id9"><code>setjmp</code> and <code>longjmp</code></a></li>
+<li><a class="reference internal" href="#c-exception-handling" id="id10">C++ Exception Handling</a></li>
+<li><a class="reference internal" href="#inline-assembly" id="id11">Inline Assembly</a></li>
+<li><p class="first"><a class="reference internal" href="#future-directions" id="id12">Future Directions</a></p>
+<ul class="small-gap">
+<li><a class="reference internal" href="#simd" id="id13">SIMD</a></li>
+<li><a class="reference internal" href="#inter-process-communication" id="id14">Inter-Process Communication</a></li>
+<li><a class="reference internal" href="#posix-style-signal-handling" id="id15">POSIX-style Signal Handling</a></li>
+<li><a class="reference internal" href="#computed-goto" id="id16">Computed <code>goto</code></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<section id="source-language-support">
+<h2 id="source-language-support">Source language support</h2>
+<p>The currently supported languages are C and C++. The PNaCl toolchain is
+based on Clang 3.3, which fully supports C++11 and most of C11. A
+detailed status of the language support is available <a class="reference external" href="http://clang.llvm.org/cxx_status.html">here</a>.</p>
+<p>For information on using languages other than C/C++, see the <a class="reference internal" href="/native-client/faq.html#other-languages"><em>FAQ
+section on other languages</em></a>.</p>
+<p>As for the standard libraries, the PNaCl toolchain is currently based on
+<code>libc++</code>, and the <code>newlib</code> standard C library (version is available
+through the macro <code>NEWLIB_VERSION</code>). <code>libstdc++</code> is also supported
+but its use is discouraged; see <a class="reference internal" href="/native-client/devguide/devcycle/building.html#building-cpp-libraries"><em>C++ standard libraries</em></a> for more
+details.</p>
+<section id="preprocessor-definitions">
+<h3 id="preprocessor-definitions">Preprocessor definitions</h3>
+<p>When compiling C/C++ code, the PNaCl toolchain defines the <code>__pnacl__</code>
+macro. In addition, <code>__native_client__</code> is defined for compatibility
+with other NaCl toolchains.</p>
+</section></section><section id="memory-model-and-atomics">
+<span id="id1"></span><h2 id="memory-model-and-atomics"><span id="id1"></span>Memory Model and Atomics</h2>
+<section id="memory-model-for-concurrent-operations">
+<h3 id="memory-model-for-concurrent-operations">Memory Model for Concurrent Operations</h3>
+<p>The memory model offered by PNaCl relies on the same coding guidelines
+as the C11/C++11 one: concurrent accesses must always occur through
+atomic primitives (offered by <a class="reference external" href="PNaClLangRef.html#atomicintrinsics">atomic intrinsics</a>), and these accesses must always
+occur with the same size for the same memory location. Visibility of
+stores is provided on a happens-before basis that relates memory
+locations to each other as the C11/C++11 standards do.</p>
+<p>Non-atomic memory accesses may be reordered, separated, elided or fused
+according to C and C++&#8217;s memory model before the pexe is created as well
+as after its creation.</p>
+<p>As in C11/C++11 some atomic accesses may be implemented with locks on
+certain platforms. The <code>ATOMIC_*_LOCK_FREE</code> macros will always be
+<code>1</code>, signifying that all types are sometimes lock-free. The
+<code>is_lock_free</code> methods and <code>atomic_is_lock_free</code> will return the
+current platform&#8217;s implementation at translation time. These macros,
+methods and functions are in the C11 header <code>&lt;stdatomic.h&gt;</code> and the
+C++11 header <code>&lt;atomic&gt;</code>.</p>
+<p>The PNaCl toolchain supports concurrent memory accesses through legacy
+GCC-style <code>__sync_*</code> builtins, as well as through C11/C++11 atomic
+primitives and the underlying <a class="reference external" href="http://gcc.gnu.org/wiki/Atomic/GCCMM">GCCMM</a> <code>__atomic_*</code>
+primitives. <code>volatile</code> memory accesses can also be used, though these
+are discouraged. See <a class="reference internal" href="#volatile-memory-accesses">Volatile Memory Accesses</a>.</p>
+<p>PNaCl supports concurrency and parallelism with some restrictions:</p>
+<ul class="small-gap">
+<li>Threading is explicitly supported and has no restrictions over what
+prevalent implementations offer. See <a class="reference internal" href="#threading">Threading</a>.</li>
+<li><code>volatile</code> and atomic operations are address-free (operations on the
+same memory location via two different addresses work atomically), as
+intended by the C11/C++11 standards. This is critical in supporting
+synchronous &#8220;external modifications&#8221; such as mapping underlying memory
+at multiple locations.</li>
+<li>Inter-process communication through shared memory is currently not
+supported. See <a class="reference internal" href="#future-directions">Future Directions</a>.</li>
+<li>Signal handling isn&#8217;t supported, PNaCl therefore promotes all
+primitives to cross-thread (instead of single-thread). This may change
+at a later date. Note that using atomic operations which aren&#8217;t
+lock-free may lead to deadlocks when handling asynchronous
+signals. See <a class="reference internal" href="#future-directions">Future Directions</a>.</li>
+<li>Direct interaction with device memory isn&#8217;t supported, and there is no
+intent to support it. The embedding sandbox&#8217;s runtime can offer APIs
+to indirectly access devices.</li>
+</ul>
+<p>Setting up the above mechanisms requires assistance from the embedding
+sandbox&#8217;s runtime (e.g. NaCl&#8217;s Pepper APIs), but using them once setup
+can be done through regular C/C++ code.</p>
+</section><section id="atomic-memory-ordering-constraints">
+<h3 id="atomic-memory-ordering-constraints">Atomic Memory Ordering Constraints</h3>
+<p>Atomics follow the same ordering constraints as in regular C11/C++11,
+but all accesses are promoted to sequential consistency (the strongest
+memory ordering) at pexe creation time. We plan to support more of the
+C11/C++11 memory orderings in the future.</p>
+<p>Some additional restrictions, following the C11/C++11 standards:</p>
+<ul class="small-gap">
+<li>Atomic accesses must at least be naturally aligned.</li>
+<li>Some accesses may not actually be atomic on certain platforms,
+requiring an implementation that uses global locks.</li>
+<li>An atomic memory location must always be accessed with atomic
+primitives, and these primitives must always be of the same bit size
+for that location.</li>
+<li>Not all memory orderings are valid for all atomic operations.</li>
+</ul>
+</section><section id="volatile-memory-accesses">
+<h3 id="volatile-memory-accesses">Volatile Memory Accesses</h3>
+<p>The C11/C++11 standards mandate that <code>volatile</code> accesses execute in
+program order (but are not fences, so other memory operations can
+reorder around them), are not necessarily atomic, and can’t be
+elided. They can be separated into smaller width accesses.</p>
+<p>Before any optimizations occur, the PNaCl toolchain transforms
+<code>volatile</code> loads and stores into sequentially consistent <code>volatile</code>
+atomic loads and stores, and applies regular compiler optimizations
+along the above guidelines. This orders <code>volatiles</code> according to the
+atomic rules, and means that fences (including <code>__sync_synchronize</code>)
+act in a better-defined manner. Regular memory accesses still do not
+have ordering guarantees with <code>volatile</code> and atomic accesses, though
+the internal representation of <code>__sync_synchronize</code> attempts to
+prevent reordering of memory accesses to objects which may escape.</p>
+<p>Relaxed ordering could be used instead, but for the first release it is
+more conservative to apply sequential consistency. Future releases may
+change what happens at compile-time, but already-released pexes will
+continue using sequential consistency.</p>
+<p>The PNaCl toolchain also requires that <code>volatile</code> accesses be at least
+naturally aligned, and tries to guarantee this alignment.</p>
+<p>The above guarantees ease the support of legacy (i.e. non-C11/C++11)
+code, and combined with builtin fences these programs can do meaningful
+cross-thread communication without changing code. They also better
+reflect the original code&#8217;s intent and guarantee better portability.</p>
+</section></section><section id="threading">
+<span id="language-support-threading"></span><h2 id="threading"><span id="language-support-threading"></span>Threading</h2>
+<p>Threading is explicitly supported through C11/C++11&#8217;s threading
+libraries as well as POSIX threads.</p>
+<p>Communication between threads should use atomic primitives as described
+in <a class="reference internal" href="#id1">Memory Model and Atomics</a>.</p>
+</section><section id="setjmp-and-longjmp">
+<h2 id="setjmp-and-longjmp"><code>setjmp</code> and <code>longjmp</code></h2>
+<p>PNaCl and NaCl support <code>setjmp</code> and <code>longjmp</code> without any
+restrictions beyond C&#8217;s.</p>
+</section><section id="c-exception-handling">
+<h2 id="c-exception-handling">C++ Exception Handling</h2>
+<p>PNaCl currently supports C++ exception handling through <code>setjmp()</code> and
+<code>longjmp()</code>, which can be enabled with the <code>--pnacl-exceptions=sjlj</code>
+linker flag. Exceptions are disabled by default so that faster and
+smaller code is generated, and <code>throw</code> statements are replaced with
+calls to <code>abort()</code>. The usual <code>-fno-exceptions</code> flag is also
+supported. PNaCl will support full zero-cost exception handling in the
+future.</p>
+<p>NaCl supports full zero-cost C++ exception handling.</p>
+</section><section id="inline-assembly">
+<h2 id="inline-assembly">Inline Assembly</h2>
+<p>Inline assembly isn&#8217;t supported by PNaCl because it isn&#8217;t portable. The
+one current exception is the common compiler barrier idiom
+<code>asm(&quot;&quot;:::&quot;memory&quot;)</code>, which gets transformed to a sequentially
+consistent memory barrier (equivalent to <code>__sync_synchronize()</code>). In
+PNaCl this barrier is only guaranteed to order <code>volatile</code> and atomic
+memory accesses, though in practice the implementation attempts to also
+prevent reordering of memory accesses to objects which may escape.</p>
+<p>NaCl supports a fairly wide subset of inline assembly through GCC&#8217;s
+inline assembly syntax, with the restriction that the sandboxing model
+for the target architecture has to be respected.</p>
+</section><section id="future-directions">
+<h2 id="future-directions">Future Directions</h2>
+<section id="simd">
+<h3 id="simd">SIMD</h3>
+<p>PNaCl currently doesn&#8217;t support SIMD. We plan to add SIMD support in the
+very near future.</p>
+<p>NaCl supports SIMD.</p>
+</section><section id="inter-process-communication">
+<h3 id="inter-process-communication">Inter-Process Communication</h3>
+<p>Inter-process communication through shared memory is currently not
+supported by PNaCl/NaCl. When implemented, it may be limited to
+operations which are lock-free on the current platform (<code>is_lock_free</code>
+methods). It will rely on the address-free properly discussed in <a class="reference internal" href="#memory-model-for-concurrent-operations">Memory
+Model for Concurrent Operations</a>.</p>
+</section><section id="posix-style-signal-handling">
+<h3 id="posix-style-signal-handling">POSIX-style Signal Handling</h3>
+<p>POSIX-style signal handling really consists of two different features:</p>
+<ul class="small-gap">
+<li><p class="first"><strong>Hardware exception handling</strong> (synchronous signals): The ability
+to catch hardware exceptions (such as memory access faults and
+division by zero) using a signal handler.</p>
+<p>PNaCl currently doesn&#8217;t support hardware exception handling.</p>
+<p>NaCl supports hardware exception handling via the
+<code>&lt;nacl/nacl_exception.h&gt;</code> interface.</p>
+</li>
+<li><p class="first"><strong>Asynchronous interruption of threads</strong> (asynchronous signals): The
+ability to asynchronously interrupt the execution of a thread,
+forcing the thread to run a signal handler.</p>
+<p>A similar feature is <strong>thread suspension</strong>: The ability to
+asynchronously suspend and resume a thread and inspect or modify its
+execution state (such as register state).</p>
+<p>Neither PNaCl nor NaCl currently support asynchronous interruption
+or suspension of threads.</p>
+</li>
+</ul>
+<p>If PNaCl were to support either of these, the interaction of
+<code>volatile</code> and atomics with same-thread signal handling would need
+to be carefully detailed.</p>
+</section><section id="computed-goto">
+<h3 id="computed-goto">Computed <code>goto</code></h3>
+<p>PNaCl currently doesn&#8217;t support computed <code>goto</code>, a non-standard
+extension to C used by some interpreters.</p>
+<p>NaCl supports computed <code>goto</code>.</p>
+</section></section></section>
+
+{{/partials.standard_nacl_article}}