Sierra Toolkit Version of the Day
config_eastl.h
00001 /*
00002 Copyright (C) 2005,2009-2010 Electronic Arts, Inc.  All rights reserved.
00003 
00004 Redistribution and use in source and binary forms, with or without
00005 modification, are permitted provided that the following conditions
00006 are met:
00007 
00008 1.  Redistributions of source code must retain the above copyright
00009     notice, this list of conditions and the following disclaimer.
00010 2.  Redistributions in binary form must reproduce the above copyright
00011     notice, this list of conditions and the following disclaimer in the
00012     documentation and/or other materials provided with the distribution.
00013 3.  Neither the name of Electronic Arts, Inc. ("EA") nor the names of
00014     its contributors may be used to endorse or promote products derived
00015     from this software without specific prior written permission.
00016 
00017 THIS SOFTWARE IS PROVIDED BY ELECTRONIC ARTS AND ITS CONTRIBUTORS "AS IS" AND ANY
00018 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00019 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00020 DISCLAIMED. IN NO EVENT SHALL ELECTRONIC ARTS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
00021 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00022 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00023 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
00024 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00025 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
00026 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027 */
00028 
00030 // EASTL/internal/config.h
00031 // Written and maintained by Paul Pedriana - 2005.
00033 
00034 
00035 #ifndef EASTL_INTERNAL_CONFIG_H
00036 #define EASTL_INTERNAL_CONFIG_H
00037 
00038 
00040 // ReadMe
00041 //
00042 // This is the EASTL configuration file. All configurable parameters of EASTL
00043 // are controlled through this file. However, all the settings here can be
00044 // manually overridden by the user. There are three ways for a user to override
00045 // the settings in this file:
00046 //
00047 //     - Simply edit this file.
00048 //     - Define EASTL_USER_CONFIG_HEADER.
00049 //     - Predefine individual defines (e.g. EASTL_ASSERT).
00050 //
00052 
00053 
00054 
00055 
00057 // EASTL_USER_CONFIG_HEADER
00058 //
00059 // This allows the user to define a header file to be #included before the
00060 // EASTL config.h contents are compiled. A primary use of this is to override
00061 // the contents of this config.h file. Note that all the settings below in
00062 // this file are user-overridable.
00063 //
00064 // Example usage:
00065 //     #define EASTL_USER_CONFIG_HEADER "MyConfigOverrides.h"
00066 //     #include <EASTL/vector.h>
00067 //
00069 
00070 #ifdef EASTL_USER_CONFIG_HEADER
00071     #include EASTL_USER_CONFIG_HEADER
00072 #endif
00073 
00074 
00075 
00077 // EASTL_EABASE_DISABLED
00078 //
00079 // The user can disable EABase usage and manually supply the configuration
00080 // via defining EASTL_EABASE_DISABLED and defining the appropriate entities
00081 // globally or via the above EASTL_USER_CONFIG_HEADER.
00082 //
00083 // Example usage:
00084 //     #define EASTL_EABASE_DISABLED
00085 //     #include <EASTL/vector.h>
00086 //
00088 
00089 #ifndef EASTL_EABASE_DISABLED
00090     #include <stk_util/util/eabase_eastl.h>
00091 #endif
00092 
00093 
00094 
00096 // VC++ bug fix.
00098 
00099 #ifdef _MSC_VER
00100     // VC8 has a bug whereby it generates a warning when malloc.h is #included
00101     // by its headers instead of by yours. There is no practical solution but
00102     // to pre-empt the #include of malloc.h with our own inclusion of it.
00103     // The only other alternative is to disable the warning globally, which is
00104     // something we try to avoid as much as possible.
00105     #pragma warning(push, 0)
00106     #include <malloc.h>
00107     #pragma warning(pop)
00108 #endif
00109 
00110 
00111 
00113 // EASTL_VERSION
00114 //
00115 // We more or less follow the conventional EA packaging approach to versioning
00116 // here. A primary distinction here is that minor versions are defined as two
00117 // digit entities (e.g. .03") instead of minimal digit entities ".3"). The logic
00118 // here is that the value is a counter and not a floating point fraction.
00119 // Note that the major version doesn't have leading zeros.
00120 //
00121 // Example version strings:
00122 //      "0.91.00"   // Major version 0, minor version 91, patch version 0.
00123 //      "1.00.00"   // Major version 1, minor and patch version 0.
00124 //      "3.10.02"   // Major version 3, minor version 10, patch version 02.
00125 //     "12.03.01"   // Major version 12, minor version 03, patch version
00126 //
00127 // Example usage:
00128 //     printf("EASTL version: %s", EASTL_VERSION);
00129 //     printf("EASTL version: %d.%d.%d", EASTL_VERSION_N / 10000 % 100, EASTL_VERSION_N / 100 % 100, EASTL_VERSION_N % 100);
00130 //
00132 
00133 #ifndef EASTL_VERSION
00134     #define EASTL_VERSION   "1.11.03"
00135     #define EASTL_VERSION_N  11103
00136 #endif
00137 
00138 
00139 
00141 // EA_PLATFORM_MICROSOFT
00142 //
00143 // Defined as 1 or undefined.
00144 // Implements support for the definition of EA_PLATFORM_MICROSOFT for the case
00145 // of using EABase versions prior to the addition of its EA_PLATFORM_MICROSOFT support.
00146 //
00147 #if (EABASE_VERSION_N < 20022) && !defined(EA_PLATFORM_MICROSOFT)
00148     #if defined(EA_PLATFORM_WINDOWS) || defined(EA_PLATFORM_XENON)
00149         #define EA_PLATFORM_MICROSOFT 1
00150     #endif
00151 #endif
00152 
00153 
00155 // EA_COMPILER_NO_STANDARD_CPP_LIBRARY
00156 //
00157 // Defined as 1 or undefined.
00158 // Implements support for the definition of EA_COMPILER_NO_STANDARD_CPP_LIBRARY for the case
00159 // of using EABase versions prior to the addition of its EA_COMPILER_NO_STANDARD_CPP_LIBRARY support.
00160 //
00161 #if (EABASE_VERSION_N < 20022) && !defined(EA_COMPILER_NO_STANDARD_CPP_LIBRARY)
00162     #if defined(EA_PLATFORM_ANDROID)
00163         #define EA_COMPILER_NO_STANDARD_CPP_LIBRARY 1
00164     #endif
00165 #endif
00166 
00167 
00169 // EA_COMPILER_NO_RTTI
00170 //
00171 // Defined as 1 or undefined.
00172 // Implements support for the definition of EA_COMPILER_NO_RTTI for the case
00173 // of using EABase versions prior to the addition of its EA_COMPILER_NO_RTTI support.
00174 //
00175 #if (EABASE_VERSION_N < 20022) && !defined(EA_COMPILER_NO_RTTI)
00176     #if defined(__SNC__) && !defined(__RTTI)
00177         #define EA_COMPILER_NO_RTTI
00178     #elif defined(__GXX_ABI_VERSION) && !defined(__GXX_RTTI)
00179         #define EA_COMPILER_NO_RTTI
00180     #elif defined(_MSC_VER) && !defined(_CPPRTTI)
00181         #define EA_COMPILER_NO_RTTI
00182     #elif defined(__MWERKS__)
00183         #if !__option(RTTI)
00184             #define EA_COMPILER_NO_RTTI
00185         #endif
00186     #endif
00187 #endif
00188 
00189 
00190 
00192 // EASTL namespace
00193 //
00194 // We define this so that users that #include this config file can reference
00195 // these namespaces without seeing any other files that happen to use them.
00197 
00199 namespace eastl
00200 {
00201     // Intentionally empty.
00202 }
00203 
00204 
00205 
00206 
00208 // EASTL_DEBUG
00209 //
00210 // Defined as an integer >= 0. Default is 1 for debug builds and 0 for
00211 // release builds. This define is also a master switch for the default value
00212 // of some other settings.
00213 //
00214 // Example usage:
00215 //    #if EASTL_DEBUG
00216 //       ...
00217 //    #endif
00218 //
00220 
00221 #ifndef EASTL_DEBUG
00222     #if defined(EA_DEBUG) || defined(_DEBUG)
00223         #define EASTL_DEBUG 1
00224     #else
00225         #define EASTL_DEBUG 0
00226     #endif
00227 #endif
00228 
00229 
00230 
00232 // EASTL_DEBUGPARAMS_LEVEL
00233 //
00234 // EASTL_DEBUGPARAMS_LEVEL controls what debug information is passed through to
00235 // the allocator by default.
00236 // This value may be defined by the user ... if not it will default to 1 for
00237 // EA_DEBUG builds, otherwise 0.
00238 //
00239 //  0 - no debug information is passed through to allocator calls.
00240 //  1 - 'name' is passed through to allocator calls.
00241 //  2 - 'name', __FILE__, and __LINE__ are passed through to allocator calls.
00242 //
00243 // This parameter mirrors the equivalent parameter in the CoreAllocator package.
00244 //
00246 
00247 #ifndef EASTL_DEBUGPARAMS_LEVEL
00248     #if EASTL_DEBUG
00249         #define EASTL_DEBUGPARAMS_LEVEL 2
00250     #else
00251         #define EASTL_DEBUGPARAMS_LEVEL 0
00252     #endif
00253 #endif
00254 
00255 
00256 
00258 // EASTL_DLL
00259 //
00260 // Defined as 0 or 1. The default is dependent on the definition of EA_DLL.
00261 // If EA_DLL is defined, then EASTL_DLL is 1, else EASTL_DLL is 0.
00262 // EA_DLL is a define that controls DLL builds within the EAConfig build system.
00263 // EASTL_DLL controls whether EASTL is built and used as a DLL.
00264 // Normally you wouldn't do such a thing, but there are use cases for such
00265 // a thing, particularly in the case of embedding C++ into C# applications.
00266 //
00267 #ifndef EASTL_DLL
00268     #if defined(EA_DLL)
00269         #define EASTL_DLL 1
00270     #else
00271         #define EASTL_DLL 0
00272     #endif
00273 #endif
00274 
00275 
00276 
00278 // EASTL_API
00279 //
00280 // This is used to label functions as DLL exports under Microsoft platforms.
00281 // If EA_DLL is defined, then the user is building EASTL as a DLL and EASTL's
00282 // non-templated functions will be exported. EASTL template functions are not
00283 // labelled as EASTL_API (and are thus not exported in a DLL build). This is
00284 // because it's not possible (or at least unsafe) to implement inline templated
00285 // functions in a DLL.
00286 //
00287 // Example usage of EASTL_API:
00288 //    EASTL_API int someVariable = 10;  // Export someVariable in a DLL build.
00289 //
00290 //    struct EASTL_API SomeClass{       // Export SomeClass and its member functions in a DLL build.
00291 //    };
00292 //
00293 //    EASTL_API void SomeFunction();    // Export SomeFunction in a DLL build.
00294 //
00295 //
00296 #if defined(EA_DLL) && !defined(EASTL_DLL)
00297     #define EASTL_DLL 1
00298 #endif
00299 
00300 #ifndef EASTL_API // If the build file hasn't already defined this to be dllexport...
00301     #if EASTL_DLL && defined(_MSC_VER)
00302         #define EASTL_API           __declspec(dllimport)
00303         #define EASTL_TEMPLATE_API  // Not sure if there is anything we can do here.
00304     #else
00305         #define EASTL_API
00306         #define EASTL_TEMPLATE_API
00307     #endif
00308 #endif
00309 
00310 
00312 // EASTL_NAME_ENABLED / EASTL_NAME / EASTL_NAME_VAL
00313 //
00314 // Used to wrap debug string names. In a release build, the definition
00315 // goes away. These are present to avoid release build compiler warnings
00316 // and to make code simpler.
00317 //
00318 // Example usage of EASTL_NAME:
00319 //    // pName will defined away in a release build and thus prevent compiler warnings.
00320 //    void allocator::set_name(const char* EASTL_NAME(pName))
00321 //    {
00322 //        #if EASTL_NAME_ENABLED
00323 //            mpName = pName;
00324 //        #endif
00325 //    }
00326 //
00327 // Example usage of EASTL_NAME_VAL:
00328 //    // "xxx" is defined to NULL in a release build.
00329 //    vector<T, Allocator>::vector(const allocator_type& allocator = allocator_type(EASTL_NAME_VAL("xxx")));
00330 //
00332 
00333 #ifndef EASTL_NAME_ENABLED
00334     #define EASTL_NAME_ENABLED EASTL_DEBUG
00335 #endif
00336 
00337 #ifndef EASTL_NAME
00338     #if EASTL_NAME_ENABLED
00339         #define EASTL_NAME(x)      x
00340         #define EASTL_NAME_VAL(x)  x
00341     #else
00342         #define EASTL_NAME(x)
00343         #define EASTL_NAME_VAL(x) ((const char*)NULL)
00344     #endif
00345 #endif
00346 
00347 
00348 
00350 // EASTL_DEFAULT_NAME_PREFIX
00351 //
00352 // Defined as a string literal. Defaults to "EASTL".
00353 // This define is used as the default name for EASTL where such a thing is
00354 // referenced in EASTL. For example, if the user doesn't specify an allocator
00355 // name for their deque, it is named "EASTL deque". However, you can override
00356 // this to say "SuperBaseball deque" by changing EASTL_DEFAULT_NAME_PREFIX.
00357 //
00358 // Example usage (which is simply taken from how deque.h uses this define):
00359 //     #ifndef EASTL_DEQUE_DEFAULT_NAME
00360 //         #define EASTL_DEQUE_DEFAULT_NAME   EASTL_DEFAULT_NAME_PREFIX " deque"
00361 //     #endif
00362 //
00363 #ifndef EASTL_DEFAULT_NAME_PREFIX
00364     #define EASTL_DEFAULT_NAME_PREFIX "EASTL"
00365 #endif
00366 
00367 
00368 
00370 // EASTL_ASSERT_ENABLED
00371 //
00372 // Defined as 0 or non-zero. Default is same as EASTL_DEBUG.
00373 // If EASTL_ASSERT_ENABLED is non-zero, then asserts will be executed via
00374 // the assertion mechanism.
00375 //
00376 // Example usage:
00377 //     #if EASTL_ASSERT_ENABLED
00378 //         EASTL_ASSERT(v.size() > 17);
00379 //     #endif
00380 //
00382 
00383 #ifndef EASTL_ASSERT_ENABLED
00384     #define EASTL_ASSERT_ENABLED EASTL_DEBUG
00385 #endif
00386 
00387 
00388 
00390 // EASTL_EMPTY_REFERENCE_ASSERT_ENABLED
00391 //
00392 // Defined as 0 or non-zero. Default is same as EASTL_ASSERT_ENABLED.
00393 // This is like EASTL_ASSERT_ENABLED, except it is for empty container
00394 // references. Sometime people like to be able to take a reference to
00395 // the front of the container, but not use it if the container is empty.
00396 // In practice it's often easier and more efficient to do this than to write
00397 // extra code to check if the container is empty.
00398 //
00399 // Example usage:
00400 //     template <typename T, typename Allocator>
00401 //     inline typename vector<T, Allocator>::reference
00402 //     vector<T, Allocator>::front()
00403 //     {
00404 //         #if EASTL_ASSERT_ENABLED
00405 //             EASTL_ASSERT(mpEnd > mpBegin);
00406 //         #endif
00407 //
00408 //         return *mpBegin;
00409 //     }
00410 //
00412 
00413 #ifndef EASTL_EMPTY_REFERENCE_ASSERT_ENABLED
00414     #define EASTL_EMPTY_REFERENCE_ASSERT_ENABLED EASTL_ASSERT_ENABLED
00415 #endif
00416 
00417 
00418 
00420 // SetAssertionFailureFunction
00421 //
00422 // Allows the user to set a custom assertion failure mechanism.
00423 //
00424 // Example usage:
00425 //     void Assert(const char* pExpression, void* pContext);
00426 //     SetAssertionFailureFunction(Assert, this);
00427 //
00429 
00430 #ifndef EASTL_ASSERTION_FAILURE_DEFINED
00431     #define EASTL_ASSERTION_FAILURE_DEFINED
00432 
00433     namespace eastl
00434     {
00435         typedef void (*EASTL_AssertionFailureFunction)(const char* pExpression, void* pContext);
00436         EASTL_API void SetAssertionFailureFunction(EASTL_AssertionFailureFunction pFunction, void* pContext);
00437 
00438         // These are the internal default functions that implement asserts.
00439         EASTL_API void AssertionFailure(const char* pExpression);
00440         EASTL_API void AssertionFailureFunctionDefault(const char* pExpression, void* pContext);
00441     }
00442 #endif
00443 
00444 
00445 
00447 // EASTL_ASSERT
00448 //
00449 // Assertion macro. Can be overridden by user with a different value.
00450 //
00451 // Example usage:
00452 //    EASTL_ASSERT(intVector.size() < 100);
00453 //
00455 
00456 #ifndef EASTL_ASSERT
00457     #if EASTL_ASSERT_ENABLED
00458         #define EASTL_ASSERT(expression) (void)((expression) || (eastl::AssertionFailure(#expression), 0))
00459     #else
00460         #define EASTL_ASSERT(expression)
00461     #endif
00462 #endif
00463 
00464 
00465 
00467 // EASTL_FAIL_MSG
00468 //
00469 // Failure macro. Can be overridden by user with a different value.
00470 //
00471 // Example usage:
00472 //    EASTL_FAIL("detected error condition!");
00473 //
00475 
00476 #ifndef EASTL_FAIL_MSG
00477     #if EASTL_ASSERT_ENABLED
00478         #define EASTL_FAIL_MSG(message) (eastl::AssertionFailure(message))
00479     #else
00480         #define EASTL_FAIL_MSG(message)
00481     #endif
00482 #endif
00483 
00484 
00485 
00486 
00488 // EASTL_CT_ASSERT / EASTL_CT_ASSERT_NAMED
00489 //
00490 // EASTL_CT_ASSERT is a macro for compile time assertion checks, useful for
00491 // validating *constant* expressions. The advantage over using EASTL_ASSERT
00492 // is that errors are caught at compile time instead of runtime.
00493 //
00494 // Example usage:
00495 //     EASTL_CT_ASSERT(sizeof(uint32_t == 4));
00496 //
00498 
00499 #if defined(EASTL_DEBUG) && !defined(EASTL_CT_ASSERT)
00500     template <bool>  struct EASTL_CT_ASSERTION_FAILURE;
00501     template <>      struct EASTL_CT_ASSERTION_FAILURE<true>{ enum { value = 1 }; }; // We create a specialization for true, but not for false.
00502     template <int x> struct EASTL_CT_ASSERTION_TEST{};
00503 
00504     #define EASTL_PREPROCESSOR_JOIN(a, b)  EASTL_PREPROCESSOR_JOIN1(a, b)
00505     #define EASTL_PREPROCESSOR_JOIN1(a, b) EASTL_PREPROCESSOR_JOIN2(a, b)
00506     #define EASTL_PREPROCESSOR_JOIN2(a, b) a##b
00507 
00508     #if defined(_MSC_VER)
00509         #define EASTL_CT_ASSERT(expression)  typedef EASTL_CT_ASSERTION_TEST< sizeof(EASTL_CT_ASSERTION_FAILURE< (bool)(expression) >)> EASTL_CT_ASSERT_FAILURE
00510     #elif defined(__ICL) || defined(__ICC)
00511         #define EASTL_CT_ASSERT(expression)  typedef char EASTL_PREPROCESSOR_JOIN(EASTL_CT_ASSERT_FAILURE_, __LINE__) [EASTL_CT_ASSERTION_FAILURE< (bool)(expression) >::value]
00512     #elif defined(__MWERKS__)
00513         #define EASTL_CT_ASSERT(expression)  enum { EASTL_PREPROCESSOR_JOIN(EASTL_CT_ASSERT_FAILURE_, __LINE__) = sizeof(EASTL_CT_ASSERTION_FAILURE< (bool)(expression) >) }
00514     #else // GCC, etc.
00515         #define EASTL_CT_ASSERT(expression)  typedef EASTL_CT_ASSERTION_TEST< sizeof(EASTL_CT_ASSERTION_FAILURE< (bool)(expression) >)> EASTL_PREPROCESSOR_JOIN1(EASTL_CT_ASSERT_FAILURE_, __LINE__)
00516     #endif
00517 #else
00518     #define EASTL_CT_ASSERT(expression)
00519 #endif
00520 
00521 
00522 
00524 // EASTL_DEBUG_BREAK
00525 //
00526 // This function causes an app to immediately stop under the debugger.
00527 // It is implemented as a macro in order to allow stopping at the site
00528 // of the call.
00529 //
00530 //
00531 // Example usage:
00532 //     EASTL_DEBUG_BREAK();
00533 //
00535 
00536 #ifndef EASTL_DEBUG_BREAK
00537     #if defined(_MSC_VER) && (_MSC_VER >= 1300)
00538         #define EASTL_DEBUG_BREAK() __debugbreak()    // This is a compiler intrinsic which will map to appropriate inlined asm for the platform.
00539     #elif defined(EA_PROCESSOR_MIPS)                  //
00540         #define EASTL_DEBUG_BREAK() asm("break")
00541     #elif defined(__SNC__)
00542         #define EASTL_DEBUG_BREAK() *(int*)(0) = 0
00543     #elif defined(EA_PLATFORM_PS3)
00544         #define EASTL_DEBUG_BREAK() asm volatile("tw 31,1,1")
00545     #elif defined(EA_PROCESSOR_POWERPC)               // Generic PowerPC.
00546         #define EASTL_DEBUG_BREAK() asm(".long 0")    // This triggers an exception by executing opcode 0x00000000.
00547     #elif (defined(EA_PROCESSOR_X86) || defined(EA_PROCESSOR_X86_64)) && defined(EA_ASM_STYLE_INTEL)
00548         #define EASTL_DEBUG_BREAK() { __asm int 3 }
00549     #elif (defined(EA_PROCESSOR_X86) || defined(EA_PROCESSOR_X86_64)) && (defined(EA_ASM_STYLE_ATT) || defined(__GNUC__))
00550         #define EASTL_DEBUG_BREAK() asm("int3")
00551     #else
00552         void EASTL_DEBUG_BREAK(); // User must define this externally.
00553     #endif
00554 #else
00555     void EASTL_DEBUG_BREAK(); // User must define this externally.
00556 #endif
00557 
00558 
00559 
00561 // EASTL_ALLOCATOR_COPY_ENABLED
00562 //
00563 // Defined as 0 or 1. Default is 0 (disabled) until some future date.
00564 // If enabled (1) then container operator= copies the allocator from the
00565 // source container. It ideally should be set to enabled but for backwards
00566 // compatibility with older versions of EASTL it is currently set to 0.
00567 //
00569 
00570 #ifndef EASTL_ALLOCATOR_COPY_ENABLED
00571     #define EASTL_ALLOCATOR_COPY_ENABLED 0
00572 #endif
00573 
00574 
00575 
00577 // EASTL_FIXED_SIZE_TRACKING_ENABLED
00578 //
00579 // Defined as an integer >= 0. Default is same as EASTL_DEBUG.
00580 // If EASTL_FIXED_SIZE_TRACKING_ENABLED is enabled, then fixed
00581 // containers in debug builds track the max count of objects
00582 // that have been in the container. This allows for the tuning
00583 // of fixed container sizes to their minimum required size.
00584 //
00586 
00587 #ifndef EASTL_FIXED_SIZE_TRACKING_ENABLED
00588     #define EASTL_FIXED_SIZE_TRACKING_ENABLED EASTL_DEBUG
00589 #endif
00590 
00591 
00592 
00594 // EASTL_RTTI_ENABLED
00595 //
00596 // Defined as 0 or 1. Default is 1 if RTTI is supported by the compiler.
00597 // This define exists so that we can use some dynamic_cast operations in the
00598 // code without warning. dynamic_cast is only used if the specifically refers
00599 // to it; EASTL won't do dynamic_cast behind your back.
00600 //
00601 // Example usage:
00602 //     #if EASTL_RTTI_ENABLED
00603 //         pChildClass = dynamic_cast<ChildClass*>(pParentClass);
00604 //     #endif
00605 //
00607 
00608 #ifndef EASTL_RTTI_ENABLED
00609     #if defined(EA_COMPILER_NO_RTTI)
00610         #define EASTL_RTTI_ENABLED 0
00611     #else
00612         #define EASTL_RTTI_ENABLED 1
00613     #endif
00614 #endif
00615 
00616 
00617 
00618 
00620 // EASTL_EXCEPTIONS_ENABLED
00621 //
00622 // Defined as 0 or 1. Default is to follow what the compiler settings are.
00623 // The user can predefine EASTL_EXCEPTIONS_ENABLED to 0 or 1; however, if the
00624 // compiler is set to disable exceptions then EASTL_EXCEPTIONS_ENABLED is
00625 // forced to a value of 0 regardless of the user predefine.
00626 //
00628 
00629 #if !defined(EASTL_EXCEPTIONS_ENABLED) || ((EASTL_EXCEPTIONS_ENABLED == 1) && defined(EA_COMPILER_NO_EXCEPTIONS))
00630     #define EASTL_EXCEPTIONS_ENABLED 0
00631 #endif
00632 
00633 
00634 
00635 
00636 
00638 // EASTL_STRING_OPT_XXXX
00639 //
00640 // Enables some options / optimizations options that cause the string class
00641 // to behave slightly different from the C++ standard basic_string. These are
00642 // options whereby you can improve performance by avoiding operations that
00643 // in practice may never occur for you.
00644 //
00646 
00647 #ifndef EASTL_STRING_OPT_CHAR_INIT
00648     // Defined as 0 or 1. Default is 1.
00649     // Defines if newly created characters are initialized to 0 or left
00650     // as random values.
00651     // The C++ string standard is to initialize chars to 0.
00652     #define EASTL_STRING_OPT_CHAR_INIT 1
00653 #endif
00654 
00655 #ifndef EASTL_STRING_OPT_EXPLICIT_CTORS
00656     // Defined as 0 or 1. Default is 0.
00657     // Defines if we should implement explicity in constructors where the C++
00658     // standard string does not. The advantage of enabling explicit constructors
00659     // is that you can do this: string s = "hello"; in addition to string s("hello");
00660     // The disadvantage of enabling explicity constructors is that there can be
00661     // silent conversions done which impede performance if the user isn't paying
00662     // attention.
00663     // C++ standard string ctors are not explicit.
00664     #define EASTL_STRING_OPT_EXPLICIT_CTORS 0
00665 #endif
00666 
00667 #ifndef EASTL_STRING_OPT_LENGTH_ERRORS
00668     // Defined as 0 or 1. Default is equal to EASTL_EXCEPTIONS_ENABLED.
00669     // Defines if we check for string values going beyond kMaxSize
00670     // (a very large value) and throw exections if so.
00671     // C++ standard strings are expected to do such checks.
00672     #define EASTL_STRING_OPT_LENGTH_ERRORS EASTL_EXCEPTIONS_ENABLED
00673 #endif
00674 
00675 #ifndef EASTL_STRING_OPT_RANGE_ERRORS
00676     // Defined as 0 or 1. Default is equal to EASTL_EXCEPTIONS_ENABLED.
00677     // Defines if we check for out-of-bounds references to string
00678     // positions and throw exceptions if so. Well-behaved code shouldn't
00679     // refence out-of-bounds positions and so shouldn't need these checks.
00680     // C++ standard strings are expected to do such range checks.
00681     #define EASTL_STRING_OPT_RANGE_ERRORS EASTL_EXCEPTIONS_ENABLED
00682 #endif
00683 
00684 #ifndef EASTL_STRING_OPT_ARGUMENT_ERRORS
00685     // Defined as 0 or 1. Default is 0.
00686     // Defines if we check for NULL ptr arguments passed to string
00687     // functions by the user and throw exceptions if so. Well-behaved code
00688     // shouldn't pass bad arguments and so shouldn't need these checks.
00689     // Also, some users believe that strings should check for NULL pointers
00690     // in all their arguments and do no-ops if so. This is very debatable.
00691     // C++ standard strings are not required to check for such argument errors.
00692     #define EASTL_STRING_OPT_ARGUMENT_ERRORS 0
00693 #endif
00694 
00695 
00696 
00698 // EASTL_ABSTRACT_STRING_ENABLED
00699 //
00700 // Defined as 0 or 1. Default is 0 until abstract string is fully tested.
00701 // Defines whether the proposed replacement for the string module is enabled.
00702 // See bonus/abstract_string.h for more information.
00703 //
00704 #ifndef EASTL_ABSTRACT_STRING_ENABLED
00705     #define EASTL_ABSTRACT_STRING_ENABLED 0
00706 #endif
00707 
00708 
00709 
00710 
00712 // EASTL_BITSET_SIZE_T
00713 //
00714 // Defined as 0 or 1. Default is 1.
00715 // Controls whether bitset uses size_t or eastl_size_t.
00716 //
00717 #ifndef EASTL_BITSET_SIZE_T
00718     #define EASTL_BITSET_SIZE_T 1
00719 #endif
00720 
00721 
00722 
00723 
00725 // EASTL_LIST_SIZE_CACHE
00726 //
00727 // Defined as 0 or 1. Default is 0.
00728 // If defined as 1, the list and slist containers (and possibly any additional
00729 // containers as well) keep a member mSize (or similar) variable which allows
00730 // the size() member function to execute in constant time (a.k.a. O(1)).
00731 // There are debates on both sides as to whether it is better to have this
00732 // cached value or not, as having it entails some cost (memory and code).
00733 // To consider: Make list size caching an optional template parameter.
00734 //
00736 
00737 #ifndef EASTL_LIST_SIZE_CACHE
00738     #define EASTL_LIST_SIZE_CACHE 0
00739 #endif
00740 
00741 #ifndef EASTL_SLIST_SIZE_CACHE
00742     #define EASTL_SLIST_SIZE_CACHE 0
00743 #endif
00744 
00745 
00746 
00748 // EASTL_MAX_STACK_USAGE
00749 //
00750 // Defined as an integer greater than zero. Default is 4000.
00751 // There are some places in EASTL where temporary objects are put on the
00752 // stack. A common example of this is in the implementation of container
00753 // swap functions whereby a temporary copy of the container is made.
00754 // There is a problem, however, if the size of the item created on the stack
00755 // is very large. This can happen with fixed-size containers, for example.
00756 // The EASTL_MAX_STACK_USAGE define specifies the maximum amount of memory
00757 // (in bytes) that the given platform/compiler will safely allow on the stack.
00758 // Platforms such as Windows will generally allow larger values than embedded
00759 // systems or console machines, but it is usually a good idea to stick with
00760 // a max usage value that is portable across all platforms, lest the user be
00761 // surprised when something breaks as it is ported to another platform.
00762 //
00764 
00765 #ifndef EASTL_MAX_STACK_USAGE
00766     #define EASTL_MAX_STACK_USAGE 4000
00767 #endif
00768 
00769 
00770 
00772 // EASTL_VA_COPY_ENABLED
00773 //
00774 // Defined as 0 or 1. Default is 1 for compilers that need it, 0 for others.
00775 // Some compilers on some platforms implement va_list whereby its contents
00776 // are destroyed upon usage, even if passed by value to another function.
00777 // With these compilers you can use va_copy to restore the a va_list.
00778 // Known compiler/platforms that destroy va_list contents upon usage include:
00779 //     CodeWarrior on PowerPC
00780 //     GCC on x86-64
00781 // However, va_copy is part of the C99 standard and not part of earlier C and
00782 // C++ standards. So not all compilers support it. VC++ doesn't support va_copy,
00783 // but it turns out that VC++ doesn't need it on the platforms it supports.
00784 // For example usage, see the EASTL string.h file.
00785 //
00787 
00788 #ifndef EASTL_VA_COPY_ENABLED
00789     #if defined(__MWERKS__) || (defined(__GNUC__) && (__GNUC__ >= 3) && (!defined(__i386__) || defined(__x86_64__)) && !defined(__ppc__) && !defined(__PPC__) && !defined(__PPC64__))
00790         #define EASTL_VA_COPY_ENABLED 1
00791     #else
00792         #define EASTL_VA_COPY_ENABLED 0
00793     #endif
00794 #endif
00795 
00796 
00797 
00799 // EASTL_LIST_PROXY_ENABLED
00800 //
00801 #if !defined(EASTL_LIST_PROXY_ENABLED)
00802     // GCC with -fstrict-aliasing has bugs (or undocumented functionality in their
00803     // __may_alias__ implementation. The compiler gets confused about function signatures.
00804     // VC8 (1400) doesn't need the proxy because it has built-in smart debugging capabilities.
00805     #if defined(EASTL_DEBUG) && (!defined(__GNUC__) || defined(__SNC__)) && (!defined(_MSC_VER) || (_MSC_VER < 1400))
00806         #define EASTL_LIST_PROXY_ENABLED 1
00807         #define EASTL_LIST_PROXY_MAY_ALIAS EASTL_MAY_ALIAS
00808     #else
00809         #define EASTL_LIST_PROXY_ENABLED 0
00810         #define EASTL_LIST_PROXY_MAY_ALIAS
00811     #endif
00812 #endif
00813 
00814 
00815 
00817 // EASTL_STD_ITERATOR_CATEGORY_ENABLED
00818 //
00819 // Defined as 0 or 1. Default is 1.
00820 // If defined as non-zero, EASTL iterator categories (iterator.h's input_iterator_tag,
00821 // forward_iterator_tag, etc.) are defined to be those from std C++ in the std
00822 // namespace. The reason for wanting to enable such a feature is that it allows
00823 // EASTL containers and algorithms to work with std STL containes and algorithms.
00824 //
00826 
00827 #ifndef EASTL_STD_ITERATOR_CATEGORY_ENABLED
00828     #define EASTL_STD_ITERATOR_CATEGORY_ENABLED 1
00829 #endif
00830 
00831 #if EASTL_STD_ITERATOR_CATEGORY_ENABLED
00832     #define EASTL_ITC_NS std
00833 #else
00834     #define EASTL_ITC_NS eastl
00835 #endif
00836 
00837 
00838 
00839 
00841 // EASTL_VALIDATION_ENABLED
00842 //
00843 // Defined as an integer >= 0. Default is to be equal to EASTL_DEBUG.
00844 // If nonzero, then a certain amount of automatic runtime validation is done.
00845 // Runtime validation is not considered the same thing as asserting that user
00846 // input values are valid. Validation refers to internal consistency checking
00847 // of the validity of containers and their iterators. Validation checking is
00848 // something that often involves significantly more than basic assertion
00849 // checking, and it may sometimes be desirable to disable it.
00850 // This macro would generally be used internally by EASTL.
00851 //
00853 
00854 #ifndef EASTL_VALIDATION_ENABLED
00855     #define EASTL_VALIDATION_ENABLED EASTL_DEBUG
00856 #endif
00857 
00858 
00859 
00860 
00862 // EASTL_VALIDATE_COMPARE
00863 //
00864 // Defined as EASTL_ASSERT or defined away. Default is EASTL_ASSERT if EASTL_VALIDATION_ENABLED is enabled.
00865 // This is used to validate user-supplied comparison functions, particularly for sorting purposes.
00866 //
00868 
00869 #ifndef EASTL_VALIDATE_COMPARE_ENABLED
00870     #define EASTL_VALIDATE_COMPARE_ENABLED EASTL_VALIDATION_ENABLED
00871 #endif
00872 
00873 #if EASTL_VALIDATE_COMPARE_ENABLED
00874     #define EASTL_VALIDATE_COMPARE EASTL_ASSERT
00875 #else
00876     #define EASTL_VALIDATE_COMPARE(expression)
00877 #endif
00878 
00879 
00880 
00882 // EASTL_VALIDATE_INTRUSIVE_LIST
00883 //
00884 // Defined as an integral value >= 0. Controls the amount of automatic validation
00885 // done by intrusive_list. A value of 0 means no automatic validation is done.
00886 // As of this writing, EASTL_VALIDATE_INTRUSIVE_LIST defaults to 0, as it makes
00887 // the intrusive_list_node become a non-POD, which may be an issue for some code.
00888 //
00890 
00891 #ifndef EASTL_VALIDATE_INTRUSIVE_LIST
00892     #define EASTL_VALIDATE_INTRUSIVE_LIST 0
00893 #endif
00894 
00895 
00896 
00898 // EASTL_FORCE_INLINE
00899 //
00900 // Defined as a "force inline" expression or defined away.
00901 // You generally don't need to use forced inlining with the Microsoft and
00902 // Metrowerks compilers, but you may need it with the GCC compiler (any version).
00903 //
00904 // Example usage:
00905 //     template <typename T, typename Allocator>
00906 //     EASTL_FORCE_INLINE typename vector<T, Allocator>::size_type
00907 //     vector<T, Allocator>::size() const
00908 //        { return mpEnd - mpBegin; }
00909 //
00911 
00912 #ifndef EASTL_FORCE_INLINE
00913     #define EASTL_FORCE_INLINE EA_FORCE_INLINE
00914 #endif
00915 
00916 
00917 
00919 // EASTL_MAY_ALIAS
00920 //
00921 // Defined as a macro that wraps the GCC may_alias attribute. This attribute
00922 // has no significance for VC++ because VC++ doesn't support the concept of
00923 // strict aliasing. Users should avoid writing code that breaks strict
00924 // aliasing rules; EASTL_MAY_ALIAS is for cases with no alternative.
00925 //
00926 // Example usage:
00927 //    uint32_t value EASTL_MAY_ALIAS;
00928 //
00929 // Example usage:
00930 //    typedef uint32_t EASTL_MAY_ALIAS value_type;
00931 //    value_type value;
00932 //
00933 #if defined(__GNUC__) && (((__GNUC__ * 100) + __GNUC_MINOR__) >= 303)
00934     #define EASTL_MAY_ALIAS __attribute__((__may_alias__))
00935 #else
00936     #define EASTL_MAY_ALIAS
00937 #endif
00938 
00939 
00940 
00942 // EASTL_LIKELY / EASTL_UNLIKELY
00943 //
00944 // Defined as a macro which gives a hint to the compiler for branch
00945 // prediction. GCC gives you the ability to manually give a hint to
00946 // the compiler about the result of a comparison, though it's often
00947 // best to compile shipping code with profiling feedback under both
00948 // GCC (-fprofile-arcs) and VC++ (/LTCG:PGO, etc.). However, there
00949 // are times when you feel very sure that a boolean expression will
00950 // usually evaluate to either true or false and can help the compiler
00951 // by using an explicity directive...
00952 //
00953 // Example usage:
00954 //    if(EASTL_LIKELY(a == 0)) // Tell the compiler that a will usually equal 0.
00955 //       { ... }
00956 //
00957 // Example usage:
00958 //    if(EASTL_UNLIKELY(a == 0)) // Tell the compiler that a will usually not equal 0.
00959 //       { ... }
00960 //
00962 
00963 #ifndef EASTL_LIKELY
00964     #if defined(__GNUC__) && (__GNUC__ >= 3)
00965         #define EASTL_LIKELY(x)   __builtin_expect(!!(x), true)
00966         #define EASTL_UNLIKELY(x) __builtin_expect(!!(x), false)
00967     #else
00968         #define EASTL_LIKELY(x)   (x)
00969         #define EASTL_UNLIKELY(x) (x)
00970     #endif
00971 #endif
00972 
00973 
00974 
00976 // EASTL_MINMAX_ENABLED
00977 //
00978 // Defined as 0 or 1; default is 1.
00979 // Specifies whether the min and max algorithms are available.
00980 // It may be useful to disable the min and max algorithems because sometimes
00981 // #defines for min and max exist which would collide with EASTL min and max.
00982 // Note that there are already alternative versions of min and max in EASTL
00983 // with the min_alt and max_alt functions. You can use these without colliding
00984 // with min/max macros that may exist.
00985 //
00987 #ifndef EASTL_MINMAX_ENABLED
00988     #define EASTL_MINMAX_ENABLED 1
00989 #endif
00990 
00991 
00992 
00994 // EASTL_NOMINMAX
00995 //
00996 // Defined as 0 or 1; default is 1.
00997 // MSVC++ has #defines for min/max which collide with the min/max algorithm
00998 // declarations. If EASTL_NOMINMAX is defined as 1, then we undefine min and
00999 // max if they are #defined by an external library. This allows our min and
01000 // max definitions in algorithm.h to work as expected. An alternative to
01001 // the enabling of EASTL_NOMINMAX is to #define NOMINMAX in your project
01002 // settings if you are compiling for Windows.
01003 // Note that this does not control the availability of the EASTL min and max
01004 // algorithms; the EASTL_MINMAX_ENABLED configuration parameter does that.
01005 //
01007 
01008 #ifndef EASTL_NOMINMAX
01009     #define EASTL_NOMINMAX 1
01010 #endif
01011 
01012 
01013 
01014 
01016 // EASTL_ALIGN_OF
01017 //
01018 // Determines the alignment of a type.
01019 //
01020 // Example usage:
01021 //    size_t alignment = EASTL_ALIGN_OF(int);
01022 //
01024 
01025 #ifndef EASTL_ALIGN_OF
01026     #if defined(__MWERKS__)
01027           #define EASTL_ALIGN_OF(type) ((size_t)__alignof__(type))
01028     #elif !defined(__GNUC__) || (__GNUC__ >= 3) // GCC 2.x doesn't do __alignof correctly all the time.
01029         #define EASTL_ALIGN_OF __alignof
01030     #else
01031         #define EASTL_ALIGN_OF(type) ((size_t)offsetof(struct{ char c; type m; }, m))
01032     #endif
01033 #endif
01034 
01035 
01036 
01037 
01039 // eastl_size_t
01040 //
01041 // Defined as an unsigned integer type, usually either size_t or uint32_t.
01042 // Defaults to uint32_t instead of size_t because the latter wastes memory
01043 // and is sometimes slower on 64 bit machines.
01044 //
01045 // Example usage:
01046 //     eastl_size_t n = intVector.size();
01047 //
01049 
01050 #ifndef EASTL_SIZE_T
01051     #if(EA_PLATFORM_WORD_SIZE == 4) // If (sizeof(size_t) == 4) and we can thus use size_t as-is...
01052         #include <stddef.h>
01053         #define EASTL_SIZE_T  size_t
01054         #define EASTL_SSIZE_T intptr_t
01055     #else
01056         #define EASTL_SIZE_T  uint32_t
01057         #define EASTL_SSIZE_T int32_t
01058     #endif
01059 #endif
01060 
01061 typedef EASTL_SIZE_T  eastl_size_t;  // Same concept as std::size_t.
01062 typedef EASTL_SSIZE_T eastl_ssize_t; // Signed version of eastl_size_t. Concept is similar to Posix's ssize_t.
01063 
01064 
01065 
01066 
01067 
01068 
01070 // AddRef / Release
01071 //
01072 // AddRef and Release are used for "intrusive" reference counting. By the term
01073 // "intrusive", we mean that the reference count is maintained by the object
01074 // and not by the user of the object. Given that an object implements referencing
01075 // counting, the user of the object needs to be able to increment and decrement
01076 // that reference count. We do that via the venerable AddRef and Release functions
01077 // which the object must supply. These defines here allow us to specify the name
01078 // of the functions. They could just as well be defined to addref and delref or
01079 // IncRef and DecRef.
01080 //
01082 
01083 #ifndef EASTLAddRef
01084     #define EASTLAddRef AddRef
01085 #endif
01086 
01087 #ifndef EASTLRelease
01088     #define EASTLRelease Release
01089 #endif
01090 
01091 
01092 
01093 
01095 // EASTL_ALLOCATOR_EXPLICIT_ENABLED
01096 //
01097 // Defined as 0 or 1. Default is 0 for now but ideally would be changed to
01098 // 1 some day. It's 0 because setting it to 1 breaks some existing code.
01099 // This option enables the allocator ctor to be explicit, which avoids
01100 // some undesirable silent conversions, especially with the string class.
01101 //
01102 // Example usage:
01103 //     class allocator
01104 //     {
01105 //     public:
01106 //         EASTL_ALLOCATOR_EXPLICIT allocator(const char* pName);
01107 //     };
01108 //
01110 
01111 #ifndef EASTL_ALLOCATOR_EXPLICIT_ENABLED
01112     #define EASTL_ALLOCATOR_EXPLICIT_ENABLED 0
01113 #endif
01114 
01115 #if EASTL_ALLOCATOR_EXPLICIT_ENABLED
01116     #define EASTL_ALLOCATOR_EXPLICIT explicit
01117 #else
01118     #define EASTL_ALLOCATOR_EXPLICIT
01119 #endif
01120 
01121 
01122 
01124 // EASTL allocator
01125 //
01126 // The EASTL allocator system allows you to redefine how memory is allocated
01127 // via some defines that are set up here. In the container code, memory is
01128 // allocated via macros which expand to whatever the user has them set to
01129 // expand to. Given that there are multiple allocator systems available,
01130 // this system allows you to configure it to use whatever system you want,
01131 // provided your system meets the requirements of this library.
01132 // The requirements are:
01133 //
01134 //     - Must be constructable via a const char* (name) parameter.
01135 //       Some uses of allocators won't require this, however.
01136 //     - Allocate a block of memory of size n and debug name string.
01137 //     - Allocate a block of memory of size n, debug name string,
01138 //       alignment a, and offset o.
01139 //     - Free memory allocated via either of the allocation functions above.
01140 //     - Provide a default allocator instance which can be used if the user
01141 //       doesn't provide a specific one.
01142 //
01144 
01145 // namespace eastl
01146 // {
01147 //     class allocator
01148 //     {
01149 //         allocator(const char* pName = NULL);
01150 //
01151 //         void* allocate(size_t n, int flags = 0);
01152 //         void* allocate(size_t n, size_t alignment, size_t offset, int flags = 0);
01153 //         void  deallocate(void* p, size_t n);
01154 //
01155 //         const char* get_name() const;
01156 //         void        set_name(const char* pName);
01157 //     };
01158 //
01159 //     allocator* GetDefaultAllocator(); // This is used for anonymous allocations.
01160 // }
01161 
01162 #ifndef EASTLAlloc // To consider: Instead of calling through pAllocator, just go directly to operator new, since that's what allocator does.
01163     #define EASTLAlloc(allocator, n) (allocator).allocate(n);
01164 #endif
01165 
01166 #ifndef EASTLAllocFlags // To consider: Instead of calling through pAllocator, just go directly to operator new, since that's what allocator does.
01167     #define EASTLAllocFlags(allocator, n, flags) (allocator).allocate(n, flags);
01168 #endif
01169 
01170 #ifndef EASTLAllocAligned
01171     #define EASTLAllocAligned(allocator, n, alignment, offset) (allocator).allocate((n), (alignment), (offset))
01172 #endif
01173 
01174 #ifndef EASTLFree
01175     #define EASTLFree(allocator, p, size) (allocator).deallocate((p), (size))
01176 #endif
01177 
01178 #ifndef EASTLAllocatorType
01179     #define EASTLAllocatorType eastl::allocator
01180 #endif
01181 
01182 #ifndef EASTLAllocatorDefault
01183     // EASTLAllocatorDefault returns the default allocator instance. This is not a global
01184     // allocator which implements all container allocations but is the allocator that is
01185     // used when EASTL needs to allocate memory internally. There are very few cases where
01186     // EASTL allocates memory internally, and in each of these it is for a sensible reason
01187     // that is documented to behave as such.
01188     #define EASTLAllocatorDefault eastl::GetDefaultAllocator
01189 #endif
01190 
01191 #endif // Header include guard
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends