cds/details/defs.h

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