src/native_client_sdk/src/doc/reference/pnacl-c-cpp-language-support.rst

   1 ============================
   2 PNaCl C/C++ Language Support
   3 ============================
   4
   5 .. contents::
   6    :local:
   7    :backlinks: none
   8    :depth: 3
   9
  10 Source language support
  11 =======================
  12
  13 The currently supported languages are C and C++. The PNaCl toolchain is
  14 based on Clang 3.3, which fully supports C++11 and most of C11. A
  15 detailed status of the language support is available `here
  16 <http://clang.llvm.org/cxx_status.html>`_.
  17
  18 For information on using languages other than C/C++, see the :ref:`FAQ
  19 section on other languages <other_languages>`.
  20
  21 As for the standard libraries, the PNaCl toolchain is currently based on
  22 ``libstdc++`` version 4.6.1, and the ``newlib`` standard C library
  23 (version is available through the macro ``NEWLIB_VERSION``).
  24 Experimental ``libc++`` support is also included; see
  25 :ref:`building_cpp_libraries` for more details.
  26
  27 Preprocessor definitions
  28 ------------------------
  29
  30 When compiling C/C++ code, the PNaCl toolchain defines the ``__pnacl__``
  31 macro. In addition, ``__native_client__`` is defined for compatibility
  32 with other NaCl toolchains.
  33
  34 .. _memory_model_and_atomics:
  35
  36 Memory Model and Atomics
  37 ========================
  38
  39 Memory Model for Concurrent Operations
  40 --------------------------------------
  41
  42 The memory model offered by PNaCl relies on the same coding guidelines
  43 as the C11/C++11 one: concurrent accesses must always occur through
  44 atomic primitives (offered by `atomic intrinsics
  45 <PNaClLangRef.html#atomicintrinsics>`_), and these accesses must always
  46 occur with the same size for the same memory location. Visibility of
  47 stores is provided on a happens-before basis that relates memory
  48 locations to each other as the C11/C++11 standards do.
  49
  50 Non-atomic memory accesses may be reordered, separated, elided or fused
  51 according to C and C++'s memory model before the pexe is created as well
  52 as after its creation.
  53
  54 As in C11/C++11 some atomic accesses may be implemented with locks on
  55 certain platforms. The ``ATOMIC_*_LOCK_FREE`` macros will always be
  56 ``1``, signifying that all types are sometimes lock-free. The
  57 ``is_lock_free`` methods and ``atomic_is_lock_free`` will return the
  58 current platform's implementation at translation time. These macros,
  59 methods and functions are in the C11 header ``<stdatomic.h>`` and the
  60 C++11 header ``<atomic>``.
  61
  62 The PNaCl toolchain supports concurrent memory accesses through legacy
  63 GCC-style ``__sync_*`` builtins, as well as through C11/C++11 atomic
  64 primitives. ``volatile`` memory accesses can also be used, though these
  65 are discouraged. See `Volatile Memory Accesses`_.
  66
  67 PNaCl supports concurrency and parallelism with some restrictions:
  68
  69 * Threading is explicitly supported and has no restrictions over what
  70   prevalent implementations offer. See `Threading`_.
  71
  72 * ``volatile`` and atomic operations are address-free (operations on the
  73   same memory location via two different addresses work atomically), as
  74   intended by the C11/C++11 standards. This is critical in supporting
  75   synchronous "external modifications" such as mapping underlying memory
  76   at multiple locations.
  77
  78 * Inter-process communication through shared memory is currently not
  79   supported. See `Future Directions`_.
  80
  81 * Signal handling isn't supported, PNaCl therefore promotes all
  82   primitives to cross-thread (instead of single-thread). This may change
  83   at a later date. Note that using atomic operations which aren't
  84   lock-free may lead to deadlocks when handling asynchronous
  85   signals. See `Future Directions`_.
  86
  87 * Direct interaction with device memory isn't supported, and there is no
  88   intent to support it. The embedding sandbox's runtime can offer APIs
  89   to indirectly access devices.
  90
  91 Setting up the above mechanisms requires assistance from the embedding
  92 sandbox's runtime (e.g. NaCl's Pepper APIs), but using them once setup
  93 can be done through regular C/C++ code.
  94
  95 Atomic Memory Ordering Constraints
  96 ----------------------------------
  97
  98 Atomics follow the same ordering constraints as in regular C11/C++11,
  99 but all accesses are promoted to sequential consistency (the strongest
 100 memory ordering) at pexe creation time. We plan to support more of the
 101 C11/C++11 memory orderings in the future.
 102
 103 Some additional restrictions, following the C11/C++11 standards:
 104
 105 - Atomic accesses must at least be naturally aligned.
 106 - Some accesses may not actually be atomic on certain platforms,
 107   requiring an implementation that uses global locks.
 108 - An atomic memory location must always be accessed with atomic
 109   primitives, and these primitives must always be of the same bit size
 110   for that location.
 111 - Not all memory orderings are valid for all atomic operations.
 112
 113 Volatile Memory Accesses
 114 ------------------------
 115
 116 The C11/C++11 standards mandate that ``volatile`` accesses execute in
 117 program order (but are not fences, so other memory operations can
 118 reorder around them), are not necessarily atomic, and can’t be
 119 elided. They can be separated into smaller width accesses.
 120
 121 Before any optimizations occur, the PNaCl toolchain transforms
 122 ``volatile`` loads and stores into sequentially consistent ``volatile``
 123 atomic loads and stores, and applies regular compiler optimizations
 124 along the above guidelines. This orders ``volatiles`` according to the
 125 atomic rules, and means that fences (including ``__sync_synchronize``)
 126 act in a better-defined manner. Regular memory accesses still do not
 127 have ordering guarantees with ``volatile`` and atomic accesses, though
 128 the internal representation of ``__sync_synchronize`` attempts to
 129 prevent reordering of memory accesses to objects which may escape.
 130
 131 Relaxed ordering could be used instead, but for the first release it is
 132 more conservative to apply sequential consistency. Future releases may
 133 change what happens at compile-time, but already-released pexes will
 134 continue using sequential consistency.
 135
 136 The PNaCl toolchain also requires that ``volatile`` accesses be at least
 137 naturally aligned, and tries to guarantee this alignment.
 138
 139 The above guarantees ease the support of legacy (i.e. non-C11/C++11)
 140 code, and combined with builtin fences these programs can do meaningful
 141 cross-thread communication without changing code. They also better
 142 reflect the original code's intent and guarantee better portability.
 143
 144 .. _language_support_threading:
 145
 146 Threading
 147 =========
 148
 149 Threading is explicitly supported through C11/C++11's threading
 150 libraries as well as POSIX threads.
 151
 152 Communication between threads should use atomic primitives as described
 153 in `Memory Model and Atomics`_.
 154
 155 ``setjmp`` and ``longjmp``
 156 ==========================
 157
 158 PNaCl and NaCl support ``setjmp`` and ``longjmp`` without any
 159 restrictions beyond C's.
 160
 161 Inline Assembly
 162 ===============
 163
 164 Inline assembly isn't supported by PNaCl because it isn't portable. The
 165 one current exception is the common compiler barrier idiom
 166 ``asm("":::"memory")``, which gets transformed to a sequentially
 167 consistent memory barrier (equivalent to ``__sync_synchronize()``). In
 168 PNaCl this barrier is only guaranteed to order ``volatile`` and atomic
 169 memory accesses, though in practice the implementation attempts to also
 170 prevent reordering of memory accesses to objects which may escape.
 171
 172 NaCl supports a fairly wide subset of inline assembly through GCC's
 173 inline assembly syntax, with the restriction that the sandboxing model
 174 for the target architecture has to be respected.
 175
 176 Future Directions
 177 =================
 178
 179 SIMD
 180 ----
 181
 182 PNaCl currently doesn't support SIMD. We plan to add SIMD support in the
 183 very near future.
 184
 185 NaCl supports SIMD.
 186
 187 Inter-Process Communication
 188 ---------------------------
 189
 190 Inter-process communication through shared memory is currently not
 191 supported by PNaCl/NaCl. When implemented, it may be limited to
 192 operations which are lock-free on the current platform (``is_lock_free``
 193 methods). It will rely on the address-free properly discussed in `Memory
 194 Model for Concurrent Operations`_.
 195
 196 Signal Handling
 197 ---------------
 198
 199 Signal handling from user code currently isn't supported by PNaCl. When
 200 supported, the impact of ``volatile`` and atomics for same-thread signal
 201 handling will need to be carefully detailed.
 202
 203 NaCl supports signal handling.
 204
 205 Exception Handling
 206 ------------------
 207
 208 PNaCl currently doesn't support exception handling. It supports the
 209 usual ``-fno-exceptions`` flag, and by default it transforms all
 210 ``throw`` statements into ``abort``. We plan to add exception-handling
 211 support in the very near future, and zero-cost exception handling soon
 212 thereafter.
 213
 214 NaCl supports exception handling.
 215
 216 Computed ``goto``
 217 -----------------
 218
 219 PNaCl currently doesn't support computed ``goto``, a non-standard
 220 extension to C used by some interpreters.
 221
 222 NaCl supports computed ``goto``.