From: khizmax Date: Sun, 21 Sep 2014 18:33:07 +0000 (+0400) Subject: Change "atomic" doc X-Git-Tag: v2.0.0~314 X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=fa6c40099e76fa4e19213fb160788eb5bd6148bf;p=libcds.git Change "atomic" doc --- diff --git a/cds/cxx11_atomic.h b/cds/cxx11_atomic.h index 5eb5e482..96be8f44 100644 --- a/cds/cxx11_atomic.h +++ b/cds/cxx11_atomic.h @@ -8,83 +8,27 @@ namespace cds { /// C++11 Atomic library support -/** @ingroup cds_cxx11_stdlib_wrapper - libcds has an implementation of C++11 atomic library (header ) - specified in N3242, p.29. - - This implementation has full support - - atomic class and its specializations for integral types and pointers - - atomic_flag class - - free atomic_xxx functions - - Exclusions: the following features specified in C++11 standard are not implemented: - - Atomic emulation. The library implements only genuine atomic operations for supported processors - - Static initialization macros (like \p ATOMIC_FLAG_INIT and others) - - \p atomic_init functions - - Internal atomic implementation is used when the standard library provided by compiler - has no C++11 \ header or it is not standard compliant, - or when \p CDS_USE_LIBCDS_ATOMIC preprocessor macro is explicitly defined in compiler command line. - The library defines \p CDS_ATOMIC macro that specifies atomic library namespace: - - \p std for compiler-provided \ library - - \p boost if you use boost.atomic library (see note below) - - \p cds::cxx11_atomic if internal \p libcds atomic implementation used - - The library has internal atomic implementation for the following processor architectures: - - Intel and AMD x86 (32bit) and amd64 (64bit) - - Intel Itanium IA64 (64bit) - - UltraSparc (64bit) - - Using \p CDS_ATOMIC macro you may call \ library functions and classes, - for example: - \code - atomics::atomic atomInt; - atomics::atomic_store_explicit( &atomInt, 0, atomics::memory_order_release ); - \endcode - - \par Microsoft Visual C++ - - MS Visual C++ has native \ header beginning from Visual C++ 2012. - However, MSVC++ 2012 has a quite inefficient implementation on atomic load/store - based on \p compare_exchange, so \p libcds does not use MSVC++ 2012 atomics. - The \p libcds library defines \p CDS_ATOMIC as - - \p cds::cxx11_atomic (internal implementation) for MS VC++ 2008, 2010, and 2012 - - \p std for MS VC++ 2013 and above. - - \par GCC - - For GCC compiler the macro \p CDS_ATOMIC is defined as: - - \p cds::cxx11_atomic by default - - \p std if the compiler version is 4.6 and \p CDS_CXX11_ATOMIC_GCC is defined (see below) - - \p std for GCC 4.7 and above - - GCC team implements full support for C++11 memory model in version 4.7 - (see http://gcc.gnu.org/wiki/Atomic/GCCMM). - \p libcds uses its own implementation of C++11 \ library located in - file for GCC version up to 4.6. This implementation almost conforms to C++11 standard draft - N3242 (see exclusions above) - that is closest to final version. - However, GCC 4.6 has the implementation of \ header in its libstdc++ - that is built on __sync_xxx (or __atomic_xxx) built-in functions. You can use libcds with GCC 4.6 - \ specifying \p CDS_CXX11_ATOMIC_GCC macro in g++ command line: - \code g++ -DCDS_CXX11_ATOMIC_GCC ... \endcode - GCC 4.6 atomic implementation does not support atomic for any type \p T. The linker - generates "undefined symbol" error for atomic if \p T is not an integral type or a pointer. It is - not essential for intrusive and non-intrusive containers represented in \p libcds. - However, cds::memory::michael memory allocator cannot be linked with GCC 4.6 \ header. - This error has been fixed in GCC 4.7. - - \par Clang - - The macro \p CDS_ATOMIC is defined as \p cds::cxx11_atomic. - \p libcds does not yet use native clang atomics. - - \par boost::atomic - - Beginning from version 1.54, boost library contains an implementation of atomic - sufficient for \p libcds. - You can compile \p libcds and your projects with boost.atomic specifying \p -DCDS_USE_BOOST_ATOMIC - in compiler's command line. +/** + \p libcds can use the following implementations of the atomics: + - STL . This is used by default + - \p boost.atomic for boost 1.54 and above. To use it you should define \p CDS_USE_BOOST_ATOMIC for + your compiler invocation, for example, for gcc specify \p -DCDS_USE_BOOST_ATOMIC + in command line + - \p libcds implementation of atomic operation according to C++11 standard as + specified in N3242, p.29. + \p libcds implementation is not the full standard compliant, it provides only C++ part of standard, + for example, \p libcds has no static initialization of the atomic variables and some other C features. + However, that imlementation is enough for the library purposes. Supported architecture: x86, amd64, + ia64 (Itanium) 64bit, 64bit Sparc. To use \p libcds atomic you should define \p CDS_USE_LIBCDS_ATOMIC + in the compiler command line (\p -DCDS_USE_LIBCDS_ATOMIC for gcc/clang). + + @note For Clang compiler \p libcds do not use compiler-provided due some problems. + Instead, \p libcds atomic is used by default, or you can try to use \p boost.atomic. + + The library defines \p atomics alias for atomic namespace: + - namespace atomics = std for STL + - namespace atomics = boost for \p boost.atomic + - namespace atomics = cds::cxx11_atomic for library-provided atomic implementation */ namespace cxx11_atomic { }} // namespace cds::cxx11_atomic