libcilkrts/include/cilk/common.h

   1 /** common.h
   2  *
   3  *  @copyright
   4  *  Copyright (C) 2010-2013, Intel Corporation
   5  *  All rights reserved.
   6  *
   7  *  @copyright
   8  *  Redistribution and use in source and binary forms, with or without
   9  *  modification, are permitted provided that the following conditions
  10  *  are met:
  11  *
  12  *    * Redistributions of source code must retain the above copyright
  13  *      notice, this list of conditions and the following disclaimer.
  14  *    * Redistributions in binary form must reproduce the above copyright
  15  *      notice, this list of conditions and the following disclaimer in
  16  *      the documentation and/or other materials provided with the
  17  *      distribution.
  18  *    * Neither the name of Intel Corporation nor the names of its
  19  *      contributors may be used to endorse or promote products derived
  20  *      from this software without specific prior written permission.
  21  *
  22  *  @copyright
  23  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  24  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  25  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  26  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  27  *  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  28  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  29  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  30  *  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  31  *  AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
  33  *  WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34  *  POSSIBILITY OF SUCH DAMAGE.
  35  */
  36
  37 /** @file common.h
  38  *
  39  * @brief Defines common macros and structures used by the Intel Cilk Plus
  40  * runtime.
  41  *
  42  *  @ingroup common
  43  */
  44
  45 /** @defgroup common Common Definitions
  46  *  Macro, structure, and class definitions used elsewhere in the runtime.
  47  *  @{
  48  */
  49
  50 #ifndef INCLUDED_CILK_COMMON
  51 #define INCLUDED_CILK_COMMON
  52
  53 #ifdef __cplusplus
  54 /** Namespace for all Cilk definitions that can be included in user code.
  55  */
  56 namespace cilk {
  57
  58     /** Namespace for definitions that are primarily intended for use
  59      *  in other Cilk definitions.
  60      */
  61     namespace internal {}
  62 }
  63 #endif
  64
  65 /** Cilk library version = 1.01
  66  */
  67 #define CILK_LIBRARY_VERSION 102
  68
  69 #ifdef __cplusplus
  70 #   include <cassert>
  71 #else
  72 #   include <assert.h>
  73 #endif
  74
  75 /**
  76  * Prefix standard library function and type names with __STDNS in order to
  77  * get correct lookup in both C and C++.
  78  */
  79 #ifdef __cplusplus
  80 #   define __STDNS std::
  81 #else
  82 #   define __STDNS
  83 #endif
  84
  85 /**
  86  * @def CILK_EXPORT
  87  * Define export of runtime functions from shared library.
  88  * Should be exported only from cilkrts*.dll/cilkrts*.so
  89  * @def CILK_EXPORT_DATA
  90  * Define export of runtime data from shared library.
  91  */
  92 #ifdef _WIN32
  93 #   ifdef IN_CILK_RUNTIME
  94 #       define CILK_EXPORT      __declspec(dllexport)
  95 #       define CILK_EXPORT_DATA __declspec(dllexport)
  96 #   else
  97 #       define CILK_EXPORT      __declspec(dllimport)
  98 #       define CILK_EXPORT_DATA __declspec(dllimport)
  99 #   endif  /* IN_CILK_RUNTIME */
 100 #elif defined(__CYGWIN__) || defined(__APPLE__) || defined(_DARWIN_C_SOURCE)
 101 #   define CILK_EXPORT      /* nothing */
 102 #   define CILK_EXPORT_DATA /* nothing */
 103 #else /* Unix/gcc */
 104 #   ifdef IN_CILK_RUNTIME
 105 #       define CILK_EXPORT      __attribute__((visibility("protected")))
 106 #       define CILK_EXPORT_DATA __attribute__((visibility("protected")))
 107 #   else
 108 #       define CILK_EXPORT      /* nothing */
 109 #       define CILK_EXPORT_DATA /* nothing */
 110 #   endif  /* IN_CILK_RUNTIME */
 111 #endif /* Unix/gcc */
 112
 113 /**
 114  * @def __CILKRTS_BEGIN_EXTERN_C
 115  * Macro to denote the start of a section in which all names have "C" linkage.
 116  * That is, none of the names are to be mangled.
 117  * @see __CILKRTS_END_EXTERN_C
 118  * @see __CILKRTS_EXTERN_C
 119  *
 120  * @def __CILKRTS_END_EXTERN_C
 121  * Macro to denote the end of a section in which all names have "C" linkage.
 122  * That is, none of the names are to be mangled.
 123  * @see __CILKRTS_BEGIN_EXTERN_C
 124  * @see __CILKRTS_EXTERN_C
 125  *
 126  * @def __CILKRTS_EXTERN_C
 127  * Macro to prefix a single definition which has "C" linkage.
 128  * That is, the defined name is not to be mangled.
 129  * @see __CILKRTS_BEGIN_EXTERN_C
 130  * @see __CILKRTS_END_EXTERN_C
 131  */
 132 #ifdef __cplusplus
 133 #   define __CILKRTS_BEGIN_EXTERN_C     extern "C" {
 134 #   define __CILKRTS_END_EXTERN_C       }
 135 #   define __CILKRTS_EXTERN_C           extern "C"
 136 #else
 137 #   define __CILKRTS_BEGIN_EXTERN_C
 138 #   define __CILKRTS_END_EXTERN_C
 139 #   define __CILKRTS_EXTERN_C
 140 #endif
 141
 142 /**
 143  * OS-independent macro to specify a function which is known to not throw
 144  * an exception.
 145  */
 146 #ifdef __cplusplus
 147 #   ifdef _WIN32
 148 #       define __CILKRTS_NOTHROW __declspec(nothrow)
 149 #   else /* Unix/gcc */
 150 #       define __CILKRTS_NOTHROW __attribute__((nothrow))
 151 #   endif /* Unix/gcc */
 152 #else
 153 #   define __CILKRTS_NOTHROW /* nothing */
 154 #endif /* __cplusplus */
 155
 156 /** Cache alignment. (Good enough for most architectures.)
 157  */
 158 #define __CILKRTS_CACHE_LINE__ 64
 159
 160 /**
 161  * Macro to specify alignment of a data member in a structure.
 162  * Because of the way that gcc’s alignment attribute is defined, @a n must
 163  * be a numeric literal, not just a compile-time constant expression.
 164  */
 165 #ifdef _WIN32
 166 #   define CILK_ALIGNAS(n) __declspec(align(n))
 167 #else /* Unix/gcc */
 168 #   define CILK_ALIGNAS(n) __attribute__((__aligned__(n)))
 169 #endif
 170
 171 /**
 172  * Macro to specify cache-line alignment of a data member in a structure.
 173  */
 174 #define __CILKRTS_CACHE_ALIGN CILK_ALIGNAS(__CILKRTS_CACHE_LINE__)
 175
 176 /**
 177  * Macro to specify a class as being at least as strictly aligned as some
 178  * type on Windows. gcc does not provide a way of doing this, so on Unix,
 179  * this just specifies the largest natural type alignment. Put the macro
 180  * between the `class` keyword and the class name:
 181  *
 182  *      class CILK_ALIGNAS_TYPE(foo) bar { ... };
 183  */
 184 #ifdef _WIN32
 185 #   define CILK_ALIGNAS_TYPE(t) __declspec(align(__alignof(t)))
 186 #else /* Unix/gcc */
 187 #   define CILK_ALIGNAS_TYPE(t) __attribute__((__aligned__))
 188 #endif
 189
 190 /**
 191  * @def CILK_API(RET_TYPE)
 192  * A function called explicitly by the programmer.
 193  * @def CILK_ABI(RET_TYPE)
 194  * A function called by compiler-generated code.
 195  * @def CILK_ABI_THROWS(RET_TYPE)
 196  * An ABI function that may throw an exception
 197  *
 198  * Even when these are the same definitions, they should be separate macros so
 199  * that they can be easily found in the code.
 200  */
 201
 202 #ifdef _WIN32
 203 #   define CILK_API(RET_TYPE) CILK_EXPORT RET_TYPE __CILKRTS_NOTHROW __cdecl
 204 #   define CILK_ABI(RET_TYPE) CILK_EXPORT RET_TYPE __CILKRTS_NOTHROW __cdecl
 205 #   define CILK_ABI_THROWS(RET_TYPE) CILK_EXPORT RET_TYPE __cdecl
 206 #else
 207 #   define CILK_API(RET_TYPE) CILK_EXPORT RET_TYPE __CILKRTS_NOTHROW
 208 #   define CILK_ABI(RET_TYPE) CILK_EXPORT RET_TYPE __CILKRTS_NOTHROW
 209 #   define CILK_ABI_THROWS(RET_TYPE) CILK_EXPORT RET_TYPE
 210 #endif
 211
 212 /**
 213  * __CILKRTS_ASSERT should be defined for debugging only, otherwise it
 214  * interferes with vectorization.  Since NDEBUG is not reliable (it must be
 215  * set by the user), we must use a platform-specific detection of debug mode.
 216  */
 217 #if defined(_WIN32) && defined(_DEBUG)
 218     /* Windows debug */
 219 #   define __CILKRTS_ASSERT(e) assert(e)
 220 #elif (! defined(_WIN32)) && ! defined(__OPTIMIZE__)
 221     /* Unix non-optimized */
 222 #   define __CILKRTS_ASSERT(e) assert(e)
 223 #elif defined __cplusplus
 224     /* C++ non-debug */
 225 #   define __CILKRTS_ASSERT(e) static_cast<void>(0)
 226 #else
 227     /* C non-debug */
 228 #   define __CILKRTS_ASSERT(e) ((void) 0)
 229 #endif
 230
 231 /**
 232  * OS-independent macro to specify a function that should be inlined
 233  */
 234 #ifdef __cpluspus
 235     // C++
 236 #   define __CILKRTS_INLINE inline
 237 #elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
 238     // C99
 239 #   define __CILKRTS_INLINE static inline
 240 #elif defined(_MSC_VER)
 241     // C89 on Windows
 242 #   define __CILKRTS_INLINE __inline
 243 #else
 244     // C89 on GCC-compatible systems
 245 #   define __CILKRTS_INLINE extern __inline__
 246 #endif
 247
 248 /**
 249  * Functions marked as CILK_EXPORT_AND_INLINE have both
 250  * inline versions defined in the Cilk API, as well as
 251  * non-inlined versions that are exported (for
 252  * compatibility with previous versions that did not
 253  * inline the functions).
 254  */
 255 #ifdef COMPILING_CILK_API_FUNCTIONS
 256 #   define CILK_EXPORT_AND_INLINE  CILK_EXPORT
 257 #else
 258 #   define CILK_EXPORT_AND_INLINE  __CILKRTS_INLINE
 259 #endif
 260
 261 /**
 262  * Try to determine if compiler supports rvalue references.
 263  */
 264 #if defined(__cplusplus) && !defined(__CILKRTS_RVALUE_REFERENCES)
 265 #   if __cplusplus >= 201103L // C++11
 266 #       define __CILKRTS_RVALUE_REFERENCES 1
 267 #   elif defined(__GXX_EXPERIMENTAL_CXX0X__)
 268 #       define __CILKRTS_RVALUE_REFERENCES 1
 269 #   elif __cplusplus >= 199711L && __cplusplus < 201103L
 270         // Compiler recognizes a language version prior to C++11
 271 #   elif __INTEL_COMPILER == 1200 && defined(__STDC_HOSTED__)
 272         // Intel compiler version 12.0
 273         // __cplusplus has a non-standard definition.  In the absence of a
 274         // proper definition, look for the C++0x macro, __STDC_HOSTED__.
 275 #       define __CILKRTS_RVALUE_REFERENCES 1
 276 #   elif __INTEL_COMPILER > 1200 && defined(CHAR16T)
 277         // Intel compiler version >= 12.1
 278         // __cplusplus has a non-standard definition.  In the absence of a
 279         // proper definition, look for the Intel macro, CHAR16T
 280 #       define __CILKRTS_RVALUE_REFERENCES 1
 281 #   endif
 282 #endif
 283
 284 /*
 285  * Include stdint.h to define the standard integer types.
 286  *
 287  * Unfortunately Microsoft doesn't provide stdint.h until Visual Studio 2010,
 288  * so use our own definitions until those are available
 289  */
 290
 291 #if ! defined(_MSC_VER) || (_MSC_VER >= 1600)
 292 #   include <stdint.h>
 293 #else
 294 #   ifndef __MS_STDINT_TYPES_DEFINED__
 295 #       define __MS_STDINT_TYPES_DEFINED__
 296         typedef signed char int8_t;
 297         typedef short int16_t;
 298         typedef int int32_t;
 299         typedef __int64 int64_t;
 300
 301         typedef unsigned char uint8_t;
 302         typedef unsigned short uint16_t;
 303         typedef unsigned int uint32_t;
 304         typedef unsigned __int64 uint64_t;
 305 #   endif  /* __MS_STDINT_TYPES_DEFINED__ */
 306 #endif  /* ! defined(_MSC_VER) || (_MSC_VER >= 1600) */
 307
 308 /**
 309  * @brief Application Binary Interface version of the Cilk runtime library.
 310  *
 311  * The ABI version is determined by the compiler used.  An object file
 312  * compiled with a higher ABI version is not compatible with a library that is
 313  * compiled with a lower ABI version.  An object file compiled with a lower
 314  * ABI version, however, can be used with a library compiled with a higher ABI
 315  * version unless otherwise stated.
 316  */
 317 #ifndef __CILKRTS_ABI_VERSION
 318 #   ifdef IN_CILK_RUNTIME
 319 #       define __CILKRTS_ABI_VERSION 1
 320 #   elif __INTEL_COMPILER > 1200
 321         // Intel compiler version >= 12.1
 322 #       define __CILKRTS_ABI_VERSION 1
 323 #   else
 324         // Compiler does not support ABI version 1
 325         // (Non-Intel compiler or Intel compiler prior to version 12.1).
 326 #       define __CILKRTS_ABI_VERSION 0
 327 #   endif
 328 #endif
 329
 330 // These structs are exported because the inlining of
 331 // the internal version of API methods require a worker
 332 // structure as parameter.
 333 __CILKRTS_BEGIN_EXTERN_C
 334     /// Worker struct, exported for inlined API methods
 335     /// @ingroup api
 336     struct __cilkrts_worker;
 337
 338     /// Worker struct, exported for inlined API methods
 339     /// @ingroup api
 340     typedef struct __cilkrts_worker __cilkrts_worker;
 341
 342     /// Worker struct pointer, exported for inlined API methods
 343     /// @ingroup api
 344     typedef struct __cilkrts_worker *__cilkrts_worker_ptr;
 345
 346
 347     /// Fetch the worker out of TLS.
 348     CILK_ABI(__cilkrts_worker_ptr) __cilkrts_get_tls_worker(void);
 349
 350     /// void *, defined to work around complaints from the compiler
 351     /// about using __declspec(nothrow) after the "void *" return type
 352     typedef void * __cilkrts_void_ptr;
 353
 354 __CILKRTS_END_EXTERN_C
 355
 356
 357 #if __CILKRTS_ABI_VERSION >= 1
 358 // Pedigree API is available only for compilers that use ABI version >= 1.
 359
 360 /** Pedigree information kept in the worker and stack frame.
 361  *  @ingroup api
 362  */
 363 typedef struct __cilkrts_pedigree
 364 {
 365     /** Rank at start of spawn helper. Saved rank for spawning functions */
 366     uint64_t rank;
 367
 368     /** Link to next in chain */
 369     const struct __cilkrts_pedigree *parent;
 370 } __cilkrts_pedigree;
 371
 372 #endif // __CILKRTS_ABI_VERSION >= 1
 373
 374 /// @}
 375
 376 #endif /* INCLUDED_CILK_COMMON */