11.2.3 Bundled Atomics Library

Atomics is a new language feature in the C11 and C++11 standards that requires runtime support from the operating system. For more information about using the atomics features, see the atomic_fence(3A), atomic_flag(3A), and stdatomic.h(3A) man pages.

Because there is not yet a standard interface for this runtime support, there are slight differences between the gcc atomics library and the Oracle Developer Studio atomics library.

GCC supports atomics with a runtime library called libatomic.so that is included in /usr/lib on Oracle Solaris 11.3 and Oracle Linux 7.x.

Oracle Developer Studio 12.6 compilers support atomics with a new runtime library called libstatomic.so. This library is bundled with the Oracle Developer Studio release, and is not included in Oracle Solaris or Linux. This is an interim solution until the GCC and Oracle Developer Studio libraries can be merged and incorporated into Oracle Solaris and until the Linux-bundled library conforms to a standard interface.

The libstatomic.so library has been tested and is compatible with the GCC 4.8, 4.9, 5.1, and 5.4 releases of libstatomic.so with a few exceptions discussed in Compatibility with GCC Atomics Library libatomic.

A new compiler option –xatomic enables you to specify whether to use the GCC libatomic library or the Oracle Developer Studio libstatomic library when linking your programs and libraries.

11.2.3.1 Selecting an Atomics Library

You can choose to use either the Oracle Developer Studio atomics library (libstatomic.so) or the GCC atomics library (libatomic.so), but it is important to make this consistent among executables and libraries that are linked together. Only one atomics library should be used in a running process.

To control which library is used at link time, use the –xatomic option. To link to Oracle Developer Studio's library libstatomic, use –xatomic=studio and to link to GCC's library libatomic, use –xatomic=gcc. To prevent linking with a library, use –xatomic=none.

As an aid to porting existing Makefiles or source code that uses GCC compilers, if –latomic is passed to the compiler, the option is converted to –xatomic=studio.

For C++ programs, the atomic support library is linked by default, when needed.

Deploying Applications that use libstatomic.so

The bundled atomics library libstatomic.so is fully supported as a part of the Oracle Developer Studio product. You can deploy an application that uses the library, but you need to include the library unless the application will run on a system where Oracle Developer Studio is installed.

1. Determine the run-time path from your executable to listatomic.so.

   For example:

   ./lib

2. Determine the build-time path to libstatomic.so.

   For example:

   build-path/import/libstatomic.so

3. Add –xatomic=none to your linking step.
4. Add new link time options.

   For example:

   –R runtime-path build-path-to-atomics/libstatomic.so.1

5. Copy the libstatomic library into your own product installation tree.

Example 3  Including libstatomic.so With a myprog Executable

The following example deploys an application on a 64-bit SPARC platform that does not have Oracle Developer Studio installed.

Before the application is built on the build machine, decide where libstatomic will be located relative to the executable. For example, if your application is located at app_root, and the libstatomic library is in app_root/lib, the relative directory of the library is ./lib.

bash-4.1$ ls app_root/
lib     myprog
bash-4.1$ ls app_root/lib/
libstatomic.so    libstatomic.so.1

On the build machine, determine where libstatomic.so is located. For example, if Oracle Developer Studio is installed in install-dir/, then libstatomic.so is located at install-dir/lib/compilers/atomic/sparcv9/libstatomic.so.

Compile the program, using the following command:

$ install-dir/bin/CC -m64 [compiler-options] -xatomic=none myprog.cc -o myprog -R'$ORIGIN'/lib install-dir/lib/compilers/atomic/sparcv9/libstatomic.so

On the deployment machine, create the package directories.

Then copy the 64-bit libstatomic.so library to app_root/lib.

$ cp install-dir/lib/compilers/atomic/sparcv9/libstatomic.so app_root/lib

Copy the resulting executable for myprog to the app_root directory. This enables the runtime linker to find libstatomic.so under ./lib when myprog is executed.

$ cp myprog.out app_root

11.2.3.2 Compatibility with GCC Atomics Library libatomic

If your application or library uses atomics and it needs to interoperate with executables and libraries which use the GCC version of libatomic, then you must link your Oracle Developer Studio program with the GCC version of libatomic. You must be careful to have only one version of the atomics runtime library in your program.

To link your Oracle Developer Studio C and C++ programs with the GCC version of libatomic, use the complier option –xatomic=gcc.

If you are linking and running on an older system that does not have the GCC version of libatomic in /usr/lib, then you do not have to worry about incompatible atomic support. In that circumstance, you can use libstatomic in combination with GCC binaries on that system, because no other atomics library will be in use.

The Oracle Developer Studio compiler works best with the libstatomic library, but is compatible with GCC's libatomic version 1.1, with the known issues listed below:

• GCC 4.8 includes libatomic 1.0.0. - This version of libatomic supports C11 and C++11 atomics, if you avoid using floating point atomics in C 11 programs. The GCC 4.8 compiler itself does not support C11 until a later release.

• GCC 4.9 and 5.1 include libatomic 1.1. - This version includes the floating-point atomics for C11, and the GCC compilers with these versions support the C11 atomics keyword.

  ---

  Note -  Your C11 program might take the address of an atomic function, which is legal only for non-generic functions. This will not work correctly with libatomic 1.0.0 or with libatomic 1.1, because the library assumes all the atomic functions will always be inlined by the compiler and don't need code in the library. You can see the list of these functions in the atomic man pages. You should use libstatomic if you need to get function pointers for these.

  ---

Oracle Linux 7.x and Oracle Solaris 11.3 include GCC 4.8 with libatomic 1.0.0.

11.2.3.3 Implementation Notes

When multiple components such as executables or shared libraries require an atomic runtime, you should dynamically link each component with the appropriate –xatomic option to create a correct dynamic dependency. You should not produce a shared library that requires an atomic option to be supplied when the library is linked.

It is not recommend to use both runtime libraries in the same process, for the following reasons:

• Some atomic types require calls to the runtime support library to perform synchronization. The two runtime systems have different internal data structures, so the two libraries cannot synchronize the same object.

• The Oracle Developer Studio library libstatomic uses the same global symbol names for functions as libatomic. If both libraries are used in the same process, an executable or library could call functions in an unexpected library.

Programs that attempt to use both runtime libraries might seem to work at first, but are likely to fail and cannot be supported.

Because many of the atomic operations are inlined, your application might be able to use the atomics feature without depending on the atomics runtime library. The behavior is implementation specific, so the results might change if you upgrade compilers. If your application uses only scalar atomic types (flags, char, int, long, or pointers) and builds on an x86 platform, then your resulting binary might not need libstatomic. You can try compiling such an application or library with the –xatomic=none option and check if it links and runs correctly.