b1f0331c7c4c84c54ffe1a1b66693e440fae8822
[libcds.git] / 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-2017
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.6+
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    External dependenies: the tests depends on:
168    - \p boost.thread (thread-loal storage support), boost.system
169    - \p google-test
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\vc14\cds.sln</tt> with Microsoft VisualStudio 2015.
180    The solution contains \p cds project and a lot of test projects. Just build the library using solution.
181
182    <b>Warning</b>: the solution depends on \p BOOST_PATH environment variable that specifies full path
183    to \p boost library root directory. The test projects search \p boost libraries in:
184    - for 32bit: <tt>\$(BOOST_PATH)/stage/lib</tt>, <tt>\$(BOOST_PATH)/stage32/lib</tt>, and <tt>\$(BOOST_PATH)/bin</tt>.
185    - for 64bit: <tt>\$(BOOST_PATH)/stage64/lib</tt> and <tt>\$(BOOST_PATH)/bin</tt>.
186
187    All tests are based on googletest framework. The following environment variables specify
188    where to find gtest include and library directories:
189    - \p GTEST_ROOT - gtest root directory. <tt>\$(GTEST_ROOT)/include</tt> specifies full path to
190         gtest include files;
191    - \p GTEST_LIB64 - the path to 64bit gtest library dir;
192    - \p GTEST_LIB32 - the path to 32bit gtest library dir.
193
194    \par *NIX build
195
196    For Unix-like systems GCC and Clang compilers are supported.
197    Use GCC 4.8+ compiler or Clang 3.6+ to build <b>cds</b> library with CMake.
198    See accompanying file <tt>/build/cmake/readme.md</tt> for more info.
199
200    @note Important for GCC compiler: all your projects that use \p libcds must be compiled with <b>-fno-strict-aliasing</b>
201    compiler flag.
202
203 */
204
205
206 /// The main library namespace
207 namespace cds {}
208
209 /*
210     \brief Basic typedefs and defines
211
212     You do not need include this header directly. All library header files depends on defs.h and include it.
213
214     Defines macros:
215
216     CDS_COMPILER        Compiler:
217                     - CDS_COMPILER_MSVC     Microsoft Visual C++
218                     - CDS_COMPILER_GCC      GNU C++
219                     - CDS_COMPILER_CLANG    clang
220                     - CDS_COMPILER_UNKNOWN  unknown compiler
221
222     CDS_COMPILER__NAME    Character compiler name
223
224     CDS_COMPILER_VERSION    Compliler version (number)
225
226     CDS_BUILD_BITS    Resulting binary code:
227                     - 32        32bit
228                     - 64        64bit
229                     - -1        undefined
230
231     CDS_POW2_BITS    CDS_BUILD_BITS == 2**CDS_POW2_BITS
232
233     CDS_PROCESSOR_ARCH    The processor architecture:
234                     - CDS_PROCESSOR_X86     Intel x86 (32bit)
235                     - CDS_PROCESSOR_AMD64   Amd64, Intel x86-64 (64bit)
236                     - CDS_PROCESSOR_IA64    Intel IA64 (Itanium)
237                     - CDS_PROCESSOR_SPARC   Sparc
238                     - CDS_PROCESSOR_PPC64   PowerPC64
239                     - CDS_PROCESSOR_ARM7    ARM v7
240                     - CDS_PROCESSOR_ARM8    ARM v8
241                     - CDS_PROCESSOR_UNKNOWN undefined processor architecture
242
243     CDS_PROCESSOR__NAME    The name (string) of processor architecture
244
245     CDS_OS_TYPE        Operating system type:
246                     - CDS_OS_UNKNOWN        unknown OS
247                     - CDS_OS_PTHREAD        unknown OS with pthread
248                     - CDS_OS_WIN32          Windows 32bit
249                     - CDS_OS_WIN64          Windows 64bit
250                     - CDS_OS_LINUX          Linux
251                     - CDS_OS_SUN_SOLARIS    Sun Solaris
252                     - CDS_OS_HPUX           HP-UX
253                     - CDS_OS_AIX            IBM AIX
254                     - CDS_OS_BSD            FreeBSD, OpenBSD, NetBSD - common flag
255                     - CDS_OS_FREE_BSD       FreeBSD
256                     - CDS_OS_OPEN_BSD       OpenBSD
257                     - CSD_OS_NET_BSD        NetBSD
258                     - CDS_OS_MINGW          MinGW
259                     - CDS_OS_OSX            Apple OS X
260
261     CDS_OS__NAME        The name (string) of operating system type
262
263     CDS_OS_INTERFACE OS interface:
264                     - CDS_OSI_UNIX             Unix (POSIX)
265                     - CDS_OSI_WINDOWS          Windows
266
267
268     CDS_BUILD_TYPE    Build type: 'RELEASE' or 'DEBUG' string
269
270 */
271
272 #if defined(_DEBUG) || !defined(NDEBUG)
273 #    define    CDS_DEBUG
274 #    define    CDS_BUILD_TYPE    "DEBUG"
275 #else
276 #    define    CDS_BUILD_TYPE    "RELEASE"
277 #endif
278
279 /// Unused function argument
280 #define CDS_UNUSED(x)   (void)(x)
281
282 // Supported compilers:
283 #define CDS_COMPILER_MSVC        1
284 #define CDS_COMPILER_GCC         2
285 #define CDS_COMPILER_INTEL       3
286 #define CDS_COMPILER_CLANG       4
287 #define CDS_COMPILER_UNKNOWN    -1
288
289 // Supported processor architectures:
290 #define CDS_PROCESSOR_X86       1
291 #define CDS_PROCESSOR_IA64      2
292 #define CDS_PROCESSOR_SPARC     3
293 #define CDS_PROCESSOR_AMD64     4
294 #define CDS_PROCESSOR_PPC64     5   // PowerPC 64bit
295 #define CDS_PROCESSOR_ARM7      7
296 #define CDS_PROCESSOR_ARM8      8
297 #define CDS_PROCESSOR_UNKNOWN   -1
298
299 // Supported OS interfaces
300 #define CDS_OSI_UNKNOWN          0
301 #define CDS_OSI_UNIX             1
302 #define CDS_OSI_WINDOWS          2
303
304 // Supported operating systems (value of CDS_OS_TYPE):
305 #define CDS_OS_UNKNOWN          -1
306 #define CDS_OS_WIN32            1
307 #define CDS_OS_WIN64            5
308 #define CDS_OS_LINUX            10
309 #define CDS_OS_SUN_SOLARIS      20
310 #define CDS_OS_HPUX             30
311 #define CDS_OS_AIX              50  // IBM AIX
312 #define CDS_OS_FREE_BSD         61
313 #define CDS_OS_OPEN_BSD         62
314 #define CDS_OS_NET_BSD          63
315 #define CDS_OS_MINGW            70
316 #define CDS_OS_OSX              80
317 #define CDS_OS_PTHREAD          100
318
319 #if defined(_MSC_VER)
320 #   if defined(__ICL) || defined(__INTEL_COMPILER)
321 #       define CDS_COMPILER CDS_COMPILER_INTEL
322 #   elif defined(__clang__)
323 #       define CDS_COMPILER CDS_COMPILER_CLANG
324 #   else
325 #       define CDS_COMPILER CDS_COMPILER_MSVC
326 #   endif
327 #elif defined(__clang__)    // Clang checking must be before GCC since Clang defines __GCC__ too
328 #   define CDS_COMPILER CDS_COMPILER_CLANG
329 #elif defined( __GCC__ ) || defined(__GNUC__)
330 #   if defined(__ICL) || defined(__INTEL_COMPILER)
331 #       define CDS_COMPILER CDS_COMPILER_INTEL
332 #   else
333 #       define CDS_COMPILER CDS_COMPILER_GCC
334 #   endif
335 #else
336 #    define CDS_COMPILER CDS_COMPILER_UNKNOWN
337 #endif  // Compiler choice
338
339
340 // CDS_VERIFY: Debug - assert(_expr); Release - _expr
341 #ifdef CDS_DEBUG
342 #   define CDS_VERIFY( _expr )       assert( _expr )
343 #   define CDS_VERIFY_FALSE( _expr ) assert( !( _expr ))
344 #   define CDS_DEBUG_ONLY( _expr )        _expr
345 #else
346 #   define CDS_VERIFY( _expr )    _expr
347 #   define CDS_VERIFY_FALSE( _expr ) _expr
348 #   define CDS_DEBUG_ONLY( _expr )
349 #endif
350
351 #ifdef CDS_STRICT
352 #   define CDS_STRICT_DO(_expr)         _expr
353 #else
354 #   define CDS_STRICT_DO( _expr )
355 #endif
356
357
358 // Compiler-specific defines
359 #include <cds/compiler/defs.h>
360
361 #define CDS_NOEXCEPT            CDS_NOEXCEPT_SUPPORT
362 #define CDS_NOEXCEPT_( expr )   CDS_NOEXCEPT_SUPPORT_( expr )
363
364 #ifdef CDS_CXX11_INLINE_NAMESPACE_SUPPORT
365 #   define CDS_CXX11_INLINE_NAMESPACE   inline
366 #else
367 #   define CDS_CXX11_INLINE_NAMESPACE
368 #endif
369
370 /*************************************************************************
371  Common things
372 **************************************************************************/
373
374 namespace cds {
375
376     /// any_type is used as a placeholder for auto-calculated type (usually in \p rebind templates)
377     struct any_type {};
378
379 } // namespace cds
380
381 #endif // #ifndef CDSLIB_DEFS_H