cds/details/defs.h

   1 //$$CDS-header$$
   2
   3 #ifndef __CDS_DEFS_H
   4 #define __CDS_DEFS_H
   5
   6 #include <stddef.h>
   7 #include <assert.h>
   8 #include <cstdint>
   9 #include <exception>
  10 #include <stdexcept>
  11 #include <string>
  12 #include <memory>
  13
  14 #include <cds/version.h>
  15
  16 /** \mainpage CDS: Concurrent Data Structures library
  17
  18    This library is a collection of lock-free and lock-based fine-grained algorithms of data structures
  19    like maps, queues, list etc. The library contains implementation of well-known data structures
  20    and memory reclamation schemas for modern processor architectures.
  21
  22    Supported processor architectures and operating systems (OS) are:
  23       - x86 [32bit] Linux, Windows, FreeBSD, MinGW
  24       - amd64 (x86-64) [64bit] Linux, Windows, FreeBSD, MinGW
  25       - ia64 (itanium) [64bit] Linux, HP-UX 11.23, HP-UX 11.31
  26       - sparc [64bit] Sun Solaris
  27       - Mac OS X amd64
  28
  29    Supported compilers:
  30       - GCC 4.3+ - for the UNIX-like OSes
  31       - Clang 3.0+ - for Linux
  32       - MS Visual C++ 2008 and above - for MS Windows
  33
  34    For each lock-free data structure the \p CDS library presents several implementation based on published papers. For
  35    example, there are several implementations of queue, each of them is divided by memory reclamation
  36    schema used. However, any implementation supports common interface for the type of data structure.
  37
  38    To implement any lock-free data structure, two things are needed:
  39    - atomic operation library conforming with C++11 memory model. The <b>libcds</b> has such feature, see cds::cxx11_atomic namespace for
  40      details and compiler-specific information.
  41    - safe memory reclamation (SMR) or garbage collecting (GC) algorithm. The <b>libcds</b> has an implementation of several
  42      well-known SMR algos, see below.
  43
  44    The main part of lock-free data structs is garbage collecting. The garbage collector (GC) solves the problem of safe
  45    memory reclamation that is one of the main problems for lock-free programming.
  46    The library contains the implementations of several light-weight \ref cds_garbage_collector "memory reclamation schemes":
  47    - M.Michael's Hazard Pointer - \p see cds::gc::HP, \p cds::gc::DHP for more explanation
  48    - User-space Read-Copy Update (RCU) - see cds::urcu namespace
  49    - there is cds::gc::nogc "GC" for containers that do not support item reclamation.
  50
  51    Many GC requires a support from the thread. The library does not define the threading model you must use,
  52    it is developed to support various ones; about incorporating <b>cds</b> library to your threading model see cds::threading.
  53
  54    The main namespace for the library is \ref cds.
  55    To see the full list of container's class go to <a href="modules.html">modules</a> tab.
  56
  57    \par How to build
  58
  59    The <b>cds</b> is mostly header-only library. Only small part of library related to GC core functionality
  60    must be compiled. The test projects depends on the following static library from \p boost:
  61    - <tt>boost_thread</tt>
  62    - <tt>boost_date_time</tt>
  63
  64    \par Windows build
  65
  66    Prerequisites: for building <b>cds</b> library and test suite you need:
  67     - <a href="http://www.activestate.com/activeperl/downloads">perl</a> installed; \p PATH environment variable
  68         should contain full path to Perl binary. Perl is used to generate large dictionary for testing purpose;
  69     - <a href="http://www.boost.org/">boost library</a> 1.51 and above. You should create environment variable
  70         \p BOOST_PATH containing full path to \p boost root directory (for example, <tt>C:\\libs\\boost_1_47_0</tt>).
  71
  72    Open solution file <tt>cds\projects\vcX\cds.sln</tt> where vcX - version of
  73    Microsoft Visual C++ you use: vc9 for MS VC 2008, vc10 for MS VC 2010 and so on. The solution
  74    contains <tt>cds</tt> project and several test projects. Just build the library using solution.
  75
  76    <b>Warning</b>: the solution depends on \p BOOST_PATH environment variable that specifies full path
  77    to \p boost library root directory. The test projects search \p boost libraries in:
  78    - for 32bit: \$(BOOST_PATH)/stage/lib, \$(BOOST_PATH)/stage32/lib, and \$(BOOST_PATH)/bin.
  79    - for 64bit: \$(BOOST_PATH)/stage64/lib and \$(BOOST_PATH)/bin.
  80
  81    \par *NIX build
  82
  83    For Unix-like systems GCC and Clang compilers are supported.
  84    Use GCC 4.3 (or above) compiler or Clang 3.0 or above to build <b>cds</b> library. The distributive contains
  85    makefile and <tt>build.sh</tt> script in <tt>build</tt> directory.
  86    The <tt>build/sample</tt> directory contains sample scripts for different operating systems and
  87    processor architectures.
  88    The <tt>build.sh</tt> script supports the following options:
  89    - <tt>-c toolset</tt> - Toolset name, possible values: <tt>gcc</tt> (default), <tt>clang</tt>
  90    - <tt>-x compiler</tt> - C++ compiler name (e.g. g++, g++-4.5 and so on)
  91    - <tt>-p arch</tt> - processor architecture; possible values for arch are: x86, amd64 (x86_64), sparc, ia64
  92    - <tt>-o OStype</tt> - OS family; possible values for OStype are: linux, sunos (solaris), hpux
  93    - <tt>-D define</tt> additional defines
  94    - <tt>-b bits</tt> - bits to build, accepts '64', '32'
  95    - <tt>-l "options"</tt> - extra linker options (in quotes)
  96    - <tt>-z "options"</tt> - extra compiler options (in quotes)
  97    - <tt>--with-boost path</tt> - path to boost include
  98    - <tt>--debug-cxx-options "options"</tt> - extra compiler options for debug target
  99    - <tt>--debug-ld-options "options"</tt> - extra linker options for debug target
 100    - <tt>--release-cxx-options "options"</tt> - extra compiler options for release target
 101    - <tt>--release-ld-options "optons"</tt> - extra linker options for release target
 102    - <tt>--clean</tt> - clean all before building
 103    - <tt>--debug-test</tt> - make unit test in debug mode; by defalt release unit test generated
 104    - <tt>--amd64-use-128bit</tt> - compile with supporting 128bit (16byte) CAS on amd64 (for am64 only)
 105
 106     <b>Important for GCC compiler</b>: all your projects that use <b>libcds</b> must be compiled with <b>-fno-strict-aliasing</b>
 107     compiler flag. Also, the compiler option <tt>-std=c++0x</tt> is very useful.
 108
 109    \anchor cds_how_to_use
 110    \par How to use
 111
 112    To use \p cds lock-free containers based on garbage collectors (GC) provided by library
 113    your application must be linked with \p libcds.
 114
 115    The main part of lock-free programming is garbage collecting for safe memory reclamation.
 116    The library provides several types of GC schemes. One of widely used and well-tested one is Hazard Pointer
 117    memory reclamation schema discovered by M. Micheal and implemented in the library as cds::gc::HP class.
 118    Usually, the application is based on only one type of GC.
 119
 120    In the next example we mean that your application uses Hazard Pointer (cds::gc::HP) - based containers.
 121
 122     First, in your code you should initialize \p cds library and a garbage collector in \p main function:
 123     \code
 124     #include <cds/init.h>       // for cds::Initialize and cds::Terminate
 125     #include <cds/gc/hp.h>      // for cds::HP (Hazard Pointer) garbage collector
 126
 127     int main(int argc, char** argv)
 128     {
 129         // Initialize libcds
 130         cds::Initialize();
 131
 132         {
 133             // Initialize Hazard Pointer singleton
 134             cds::gc::HP hpGC;
 135
 136             // If main thread uses lock-free containers
 137             // the main thread should be attached to libcds infrastructure
 138             cds::threading::Manager::attachThread();
 139
 140             // Now you can use HP-based containers in the main thread
 141             //...
 142         }
 143
 144         // Terminate libcds
 145         cds::Terminate();
 146     }
 147     \endcode
 148
 149     Second, any of your thread should be attached to \p cds infrastructure.
 150     \code
 151     #include <cds/gc/hp.h>
 152
 153     int myThreadEntryPoint(void *)
 154     {
 155         // Attach the thread to libcds infrastructure
 156         cds::threading::Manager::attachThread();
 157
 158         // Now you can use HP-based containers in the thread
 159         //...
 160
 161         // Detach thread when terminating
 162         cds::threading::Manager::detachThread();
 163     }
 164     \endcode
 165
 166     After that, you can use \p cds lock-free containers safely without any external synchronization.
 167
 168     In some cases, you should work in an external thread. For example, your application
 169     is a plug-in for a server that calls your code in a thread that has been created by the server.
 170     In this case, you should use persistent mode of garbage collecting. In this mode, the thread attaches
 171     to the GC singleton only if it is not attached yet and never call detaching:
 172     \code
 173     #include <cds/gc/hp.h>
 174
 175     int plugin_entry_point()
 176     {
 177         // Attach the thread if it is not attached yet
 178         if ( !cds::threading::Manager::isThreadAttached() )
 179             cds::threading::Manager::attachThread();
 180
 181         // Do some work with HP-related containers
 182         ...
 183     }
 184     \endcode
 185
 186 */
 187
 188
 189 /// The main library namespace
 190 namespace cds {}
 191
 192 /*
 193     \brief Basic typedefs and defines
 194
 195     You do not need include this header directly. All library header files depends on defs.h and include it.
 196
 197     Defines macros:
 198
 199     CDS_COMPILER        Compiler:
 200                     - CDS_COMPILER_MSVC     Microsoft Visual C++
 201                     - CDS_COMPILER_GCC      GNU C++
 202                     - CDS_COMPILER_CLANG    clang
 203                     - CDS_COMPILER_UNKNOWN  unknown compiler
 204
 205     CDS_COMPILER__NAME    Character compiler name
 206
 207     CDS_COMPILER_VERSION    Compliler version (number)
 208
 209     CDS_BUILD_BITS    Resulting binary code:
 210                     - 32        32bit
 211                     - 64        64bit
 212                     - -1        undefined
 213
 214     CDS_POW2_BITS    CDS_BUILD_BITS == 2**CDS_POW2_BITS
 215
 216     CDS_PROCESSOR_ARCH    The processor architecture:
 217                     - CDS_PROCESSOR_X86     Intel x86 (32bit)
 218                     - CDS_PROCESSOR_AMD64   Amd64, Intel x86-64 (64bit)
 219                     - CDS_PROCESSOR_IA64    Intel IA64 (Itanium)
 220                     - CDS_PROCESSOR_SPARC   Sparc
 221                     - CDS_PROCESSOR_PPC64   PowerPC64
 222                     - CDS_PROCESSOR_ARM7    ARM v7
 223                     - CDS_PROCESSOR_UNKNOWN undefined processor architecture
 224
 225     CDS_PROCESSOR__NAME    The name (string) of processor architecture
 226
 227     CDS_OS_TYPE        Operating system type:
 228                     - CDS_OS_UNKNOWN        unknown OS
 229                     - CDS_OS_PTHREAD        unknown OS with pthread
 230                     - CDS_OS_WIN32          Windows 32bit
 231                     - CDS_OS_WIN64          Windows 64bit
 232                     - CDS_OS_LINUX          Linux
 233                     - CDS_OS_SUN_SOLARIS    Sun Solaris
 234                     - CDS_OS_HPUX           HP-UX
 235                     - CDS_OS_AIX            IBM AIX
 236                     - CDS_OS_BSD            FreeBSD, OpenBSD, NetBSD - common flag
 237                     - CDS_OS_FREE_BSD       FreeBSD
 238                     - CDS_OS_OPEN_BSD       OpenBSD
 239                     - CSD_OS_NET_BSD        NetBSD
 240                     - CDS_OS_MINGW          MinGW
 241                     - CDS_OS_OSX            Apple OS X
 242
 243     CDS_OS__NAME        The name (string) of operating system type
 244
 245     CDS_OS_INTERFACE OS interface:
 246                     - CDS_OSI_UNIX             Unix (POSIX)
 247                     - CDS_OSI_WINDOWS          Windows
 248
 249
 250     CDS_BUILD_TYPE    Build type: 'RELEASE' or 'DEBUG' string
 251
 252 */
 253
 254 #if defined(_DEBUG) || !defined(NDEBUG)
 255 #    define    CDS_DEBUG
 256 #    define    CDS_BUILD_TYPE    "DEBUG"
 257 #else
 258 #    define    CDS_BUILD_TYPE    "RELEASE"
 259 #endif
 260
 261 /// Unused function argument
 262 #define CDS_UNUSED(x)   (void)(x)
 263
 264 // Supported compilers:
 265 #define CDS_COMPILER_MSVC        1
 266 #define CDS_COMPILER_GCC         2
 267 #define CDS_COMPILER_INTEL       3
 268 #define CDS_COMPILER_CLANG       4
 269 #define CDS_COMPILER_UNKNOWN    -1
 270
 271 // Supported processor architectures:
 272 #define CDS_PROCESSOR_X86       1
 273 #define CDS_PROCESSOR_IA64      2
 274 #define CDS_PROCESSOR_SPARC     3
 275 #define CDS_PROCESSOR_AMD64     4
 276 #define CDS_PROCESSOR_PPC64     5   // PowerPC 64bit
 277 #define CDS_PROCESSOR_ARM7      7
 278 #define CDS_PROCESSOR_UNKNOWN   -1
 279
 280 // Supported OS interfaces
 281 #define CDS_OSI_UNKNOWN          0
 282 #define CDS_OSI_UNIX             1
 283 #define CDS_OSI_WINDOWS          2
 284
 285 // Supported operating systems (value of CDS_OS_TYPE):
 286 #define CDS_OS_UNKNOWN          -1
 287 #define CDS_OS_WIN32            1
 288 #define CDS_OS_WIN64            5
 289 #define CDS_OS_LINUX            10
 290 #define CDS_OS_SUN_SOLARIS      20
 291 #define CDS_OS_HPUX             30
 292 #define CDS_OS_AIX              50  // IBM AIX
 293 #define CDS_OS_FREE_BSD         61
 294 #define CDS_OS_OPEN_BSD         62
 295 #define CDS_OS_NET_BSD          63
 296 #define CDS_OS_MINGW            70
 297 #define CDS_OS_OSX              80
 298 #define CDS_OS_PTHREAD          100
 299
 300 #if defined(_MSC_VER)
 301 #   if defined(__ICL) || defined(__INTEL_COMPILER)
 302 #       define CDS_COMPILER CDS_COMPILER_INTEL
 303 #   else
 304 #       define CDS_COMPILER CDS_COMPILER_MSVC
 305 #   endif
 306 #elif defined(__clang__)    // Clang checking must be before GCC since Clang defines __GCC__ too
 307 #   define CDS_COMPILER CDS_COMPILER_CLANG
 308 #elif defined( __GCC__ ) || defined(__GNUC__)
 309 #   if defined(__ICL) || defined(__INTEL_COMPILER)
 310 #       define CDS_COMPILER CDS_COMPILER_INTEL
 311 #   else
 312 #       define CDS_COMPILER CDS_COMPILER_GCC
 313 #   endif
 314 #else
 315 #    define CDS_COMPILER CDS_COMPILER_UNKNOWN
 316 #endif  // Compiler choice
 317
 318
 319 // CDS_VERIFY: Debug - assert(_expr); Release - _expr
 320 #ifdef CDS_DEBUG
 321 #   define CDS_VERIFY( _expr )    assert( _expr )
 322 #   define CDS_DEBUG_ONLY( _expr )        _expr
 323 #else
 324 #   define CDS_VERIFY( _expr )    _expr
 325 #   define CDS_DEBUG_ONLY( _expr )
 326 #endif
 327
 328 #ifdef CDS_STRICT
 329 #   define CDS_STRICT_DO(_expr)         _expr
 330 #else
 331 #   define CDS_STRICT_DO( _expr )
 332 #endif
 333
 334
 335 // Compiler-specific defines
 336 #include <cds/compiler/defs.h>
 337
 338 #define CDS_NOEXCEPT            CDS_NOEXCEPT_SUPPORT
 339 #define CDS_NOEXCEPT_( expr )   CDS_NOEXCEPT_SUPPORT_( expr )
 340
 341 #ifdef CDS_CXX11_INLINE_NAMESPACE_SUPPORT
 342 #   define CDS_CXX11_INLINE_NAMESPACE   inline
 343 #else
 344 #   define CDS_CXX11_INLINE_NAMESPACE
 345 #endif
 346
 347 //@cond
 348 // typedefs for back compatibility
 349 namespace cds {
 350     /// Atomic pointer
 351     typedef void *            pointer_t;
 352
 353     /// 64bit unaligned int
 354     typedef int64_t     atomic64_unaligned;
 355
 356     /// 64bit unaligned unsigned int
 357     typedef uint64_t  atomic64u_unaligned;
 358
 359     /// 64bit aligned int
 360     typedef atomic64_unaligned CDS_TYPE_ALIGNMENT(8)    atomic64_aligned;
 361
 362     /// 64bit aligned unsigned int
 363     typedef atomic64u_unaligned CDS_TYPE_ALIGNMENT(8)   atomic64u_aligned;
 364
 365     /// 64bit atomic int (aligned)
 366     typedef atomic64_aligned    atomic64_t;
 367
 368     /// 64bit atomic unsigned int (aligned)
 369     typedef atomic64u_aligned   atomic64u_t;
 370
 371     /// 32bit atomic int
 372     typedef int32_t     atomic32_t;
 373
 374     /// 32bit atomic unsigned int
 375     typedef uint32_t    atomic32u_t;
 376
 377     /// atomic int
 378     typedef atomic32_t          atomic_t;
 379
 380     /// atomic unsigned int
 381     typedef atomic32u_t         unsigned_atomic_t;
 382
 383     /// atomic int sized as pointer
 384     typedef intptr_t ptr_atomic_t;
 385
 386     /// atomic unsigned int sized as pointer
 387     typedef uintptr_t uptr_atomic_t;
 388 } // namespace cds
 389 //@endcond
 390
 391 /*************************************************************************
 392  Common things
 393 **************************************************************************/
 394
 395 namespace cds {
 396
 397     /// any_type is used as a placeholder for auto-calculated type (usually in \p rebind templates)
 398     struct any_type {};
 399
 400 } // namespace cds
 401
 402 #endif // #ifndef __CDS_DEFS_H