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 ``libc++``, and the ``newlib`` standard C library (version is available
  23 through the macro ``NEWLIB_VERSION``). ``libstdc++`` is also supported
  24 but its use is discouraged; see :ref:`building_cpp_libraries` for more
  25 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 and the underlying `GCCMM
  65 <http://gcc.gnu.org/wiki/Atomic/GCCMM>`_ ``__atomic_*``
  66 primitives. ``volatile`` memory accesses can also be used, though these
  67 are discouraged. See `Volatile Memory Accesses`_.
  68
  69 PNaCl supports concurrency and parallelism with some restrictions:
  70
  71 * Threading is explicitly supported and has no restrictions over what
  72   prevalent implementations offer. See `Threading`_.
  73
  74 * ``volatile`` and atomic operations are address-free (operations on the
  75   same memory location via two different addresses work atomically), as
  76   intended by the C11/C++11 standards. This is critical in supporting
  77   synchronous "external modifications" such as mapping underlying memory
  78   at multiple locations.
  79
  80 * Inter-process communication through shared memory is currently not
  81   supported. See `Future Directions`_.
  82
  83 * Signal handling isn't supported, PNaCl therefore promotes all
  84   primitives to cross-thread (instead of single-thread). This may change
  85   at a later date. Note that using atomic operations which aren't
  86   lock-free may lead to deadlocks when handling asynchronous
  87   signals. See `Future Directions`_.
  88
  89 * Direct interaction with device memory isn't supported, and there is no
  90   intent to support it. The embedding sandbox's runtime can offer APIs
  91   to indirectly access devices.
  92
  93 Setting up the above mechanisms requires assistance from the embedding
  94 sandbox's runtime (e.g. NaCl's Pepper APIs), but using them once setup
  95 can be done through regular C/C++ code.
  96
  97 Atomic Memory Ordering Constraints
  98 ----------------------------------
  99
 100 Atomics follow the same ordering constraints as in regular C11/C++11,
 101 but all accesses are promoted to sequential consistency (the strongest
 102 memory ordering) at pexe creation time. We plan to support more of the
 103 C11/C++11 memory orderings in the future.
 104
 105 Some additional restrictions, following the C11/C++11 standards:
 106
 107 - Atomic accesses must at least be naturally aligned.
 108 - Some accesses may not actually be atomic on certain platforms,
 109   requiring an implementation that uses global locks.
 110 - An atomic memory location must always be accessed with atomic
 111   primitives, and these primitives must always be of the same bit size
 112   for that location.
 113 - Not all memory orderings are valid for all atomic operations.
 114
 115 Volatile Memory Accesses
 116 ------------------------
 117
 118 The C11/C++11 standards mandate that ``volatile`` accesses execute in
 119 program order (but are not fences, so other memory operations can
 120 reorder around them), are not necessarily atomic, and can’t be
 121 elided. They can be separated into smaller width accesses.
 122
 123 Before any optimizations occur, the PNaCl toolchain transforms
 124 ``volatile`` loads and stores into sequentially consistent ``volatile``
 125 atomic loads and stores, and applies regular compiler optimizations
 126 along the above guidelines. This orders ``volatiles`` according to the
 127 atomic rules, and means that fences (including ``__sync_synchronize``)
 128 act in a better-defined manner. Regular memory accesses still do not
 129 have ordering guarantees with ``volatile`` and atomic accesses, though
 130 the internal representation of ``__sync_synchronize`` attempts to
 131 prevent reordering of memory accesses to objects which may escape.
 132
 133 Relaxed ordering could be used instead, but for the first release it is
 134 more conservative to apply sequential consistency. Future releases may
 135 change what happens at compile-time, but already-released pexes will
 136 continue using sequential consistency.
 137
 138 The PNaCl toolchain also requires that ``volatile`` accesses be at least
 139 naturally aligned, and tries to guarantee this alignment.
 140
 141 The above guarantees ease the support of legacy (i.e. non-C11/C++11)
 142 code, and combined with builtin fences these programs can do meaningful
 143 cross-thread communication without changing code. They also better
 144 reflect the original code's intent and guarantee better portability.
 145
 146 .. _language_support_threading:
 147
 148 Threading
 149 =========
 150
 151 Threading is explicitly supported through C11/C++11's threading
 152 libraries as well as POSIX threads.
 153
 154 Communication between threads should use atomic primitives as described
 155 in `Memory Model and Atomics`_.
 156
 157 ``setjmp`` and ``longjmp``
 158 ==========================
 159
 160 PNaCl and NaCl support ``setjmp`` and ``longjmp`` without any
 161 restrictions beyond C's.
 162
 163 C++ Exception Handling
 164 ======================
 165
 166 PNaCl currently supports C++ exception handling through ``setjmp()`` and
 167 ``longjmp()``, which can be enabled with the ``--pnacl-exceptions=sjlj``
 168 linker flag. Exceptions are disabled by default so that faster and
 169 smaller code is generated, and ``throw`` statements are replaced with
 170 calls to ``abort()``. The usual ``-fno-exceptions`` flag is also
 171 supported. PNaCl will support full zero-cost exception handling in the
 172 future.
 173
 174 NaCl supports full zero-cost C++ exception handling.
 175
 176 Inline Assembly
 177 ===============
 178
 179 Inline assembly isn't supported by PNaCl because it isn't portable. The
 180 one current exception is the common compiler barrier idiom
 181 ``asm("":::"memory")``, which gets transformed to a sequentially
 182 consistent memory barrier (equivalent to ``__sync_synchronize()``). In
 183 PNaCl this barrier is only guaranteed to order ``volatile`` and atomic
 184 memory accesses, though in practice the implementation attempts to also
 185 prevent reordering of memory accesses to objects which may escape.
 186
 187 NaCl supports a fairly wide subset of inline assembly through GCC's
 188 inline assembly syntax, with the restriction that the sandboxing model
 189 for the target architecture has to be respected.
 190
 191 Future Directions
 192 =================
 193
 194 SIMD
 195 ----
 196
 197 PNaCl currently doesn't support SIMD. We plan to add SIMD support in the
 198 very near future.
 199
 200 NaCl supports SIMD.
 201
 202 Inter-Process Communication
 203 ---------------------------
 204
 205 Inter-process communication through shared memory is currently not
 206 supported by PNaCl/NaCl. When implemented, it may be limited to
 207 operations which are lock-free on the current platform (``is_lock_free``
 208 methods). It will rely on the address-free properly discussed in `Memory
 209 Model for Concurrent Operations`_.
 210
 211 POSIX-style Signal Handling
 212 ---------------------------
 213
 214 POSIX-style signal handling really consists of two different features:
 215
 216 * **Hardware exception handling** (synchronous signals): The ability
 217   to catch hardware exceptions (such as memory access faults and
 218   division by zero) using a signal handler.
 219
 220   PNaCl currently doesn't support hardware exception handling.
 221
 222   NaCl supports hardware exception handling via the
 223   ``<nacl/nacl_exception.h>`` interface.
 224
 225 * **Asynchronous interruption of threads** (asynchronous signals): The
 226   ability to asynchronously interrupt the execution of a thread,
 227   forcing the thread to run a signal handler.
 228
 229   A similar feature is **thread suspension**: The ability to
 230   asynchronously suspend and resume a thread and inspect or modify its
 231   execution state (such as register state).
 232
 233   Neither PNaCl nor NaCl currently support asynchronous interruption
 234   or suspension of threads.
 235
 236 If PNaCl were to support either of these, the interaction of
 237 ``volatile`` and atomics with same-thread signal handling would need
 238 to be carefully detailed.
 239
 240 Computed ``goto``
 241 -----------------
 242
 243 PNaCl currently doesn't support computed ``goto``, a non-standard
 244 extension to C used by some interpreters.
 245
 246 NaCl supports computed ``goto``.