1 martin 1.4 //%LICENSE////////////////////////////////////////////////////////////////

  2 martin 1.5 //

  3 martin 1.4 // Licensed to The Open Group (TOG) under one or more contributor license
  4            // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
  5            // this work for additional information regarding copyright ownership.
  6            // Each contributor licenses this file to you under the OpenPegasus Open
  7            // Source License; you may not use this file except in compliance with the
  8            // License.

  9 martin 1.5 //

 10 martin 1.4 // Permission is hereby granted, free of charge, to any person obtaining a
 11            // copy of this software and associated documentation files (the "Software"),
 12            // to deal in the Software without restriction, including without limitation
 13            // the rights to use, copy, modify, merge, publish, distribute, sublicense,
 14            // and/or sell copies of the Software, and to permit persons to whom the
 15            // Software is furnished to do so, subject to the following conditions:

 16 martin 1.5 //

 17 martin 1.4 // The above copyright notice and this permission notice shall be included
 18            // in all copies or substantial portions of the Software.

 19 martin 1.5 //

 20 martin 1.4 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS

 21 martin 1.5 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 22 martin 1.4 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 23            // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 24            // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 25            // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 26            // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 27 martin 1.5 //

 28 martin 1.4 //////////////////////////////////////////////////////////////////////////

 29 mike   1.2 //
 30            //%/////////////////////////////////////////////////////////////////////////////
 31            
 32            #ifndef Pegasus_Magic_h
 33            #define Pegasus_Magic_h
 34            
 35            #include <Pegasus/Common/Config.h>
 36            
 37            PEGASUS_NAMESPACE_BEGIN
 38            
 39            /** The Magic class implements a convenient way to use magic numbers in

 40 kumpf  1.3     user-defined classes. Magic numbers help detect use of uninitialized,

 41 mike   1.2     destructed, or corrupted objects.
 42            

 43 kumpf  1.3     To instrument a class to use magic numbers simply add a class member

 44 mike   1.2     of type Magic<> as shown in thsi example:
 45            

 46 kumpf  1.3         \code
 47                    class MyClass
 48                    {
 49                    public:

 50 mike   1.2 

 51 kumpf  1.3             MyClass();

 52 mike   1.2 

 53 kumpf  1.3             ~MyClass();

 54 mike   1.2 

 55 kumpf  1.3             void foo();

 56 mike   1.2 

 57 kumpf  1.3         private:
 58                        Magic<0xC531B144> _magic;
 59                    };
 60                    \endcode

 61 mike   1.2 
 62                Choose whatever number you like for a magic number. The number above was

 63 kumpf  1.3     generated by the Linux uuidgen utility (Windows has a utility with the

 64 mike   1.2     same name).
 65            
 66                To test magic number, add the following expression wherever necessary
 67                (usually as the first line of every member function).
 68            

 69 kumpf  1.3         \code

 70 karl   1.5.8.2         PEGASUS_ASSERT_DEBUG(_magic);

 71 kumpf  1.3             \endcode

 72 mike   1.2     
 73                    Here's a typical example:
 74                

 75 kumpf  1.3             \code
 76                        MyClass::~MyClass()
 77                        {

 78 karl   1.5.8.2             PEGASUS_ASSERT_DEBUG(_magic);

 79 kumpf  1.3             }
 80                        \endcode

 81 mike   1.2     
 82                    This tests whether the magic number is 0xC531B144 and asserts if it is
 83                    not.
 84                
 85                    Note that using a magic number makes the user-defined class 4 bytes larger
 86                    but there is no run-time overhead unless you compile with PEGASUS_DEBUG.
 87                    The Magic constructor and destructor are empty without PEGASUS_DEBUG and
 88                    are discarded by the compiler.
 89                
 90                    CAUTION: You may be tempted to compile out the magic member when
 91                    PEGASUS_DEBUG undefined. However, this will causes unpredictable
 92                    behavior when debug libraries are mixed with non-debug libraries. The
 93                    structure alignment and size will be different and will lead to crashes.
 94                    This is only safe if a class is internal to a library.
 95                */
 96                template<Uint32 MAGIC_NUMBER>
 97                class Magic
 98                {
 99                public:
100                
101                    /** Default constructor. Sets the magic number.
102 mike   1.2         */

103 kumpf  1.3         Magic()

104 mike   1.2         {
105                #ifdef PEGASUS_DEBUG

106 kumpf  1.3             _magic = MAGIC_NUMBER;

107 mike   1.2     #endif
108                    }
109                
110                    /** Destructor. Clears the magic number (with the pattern 0xDDDDDDDD).
111                    */

112 kumpf  1.3         ~Magic()

113 mike   1.2         {
114                #ifdef PEGASUS_DEBUG

115 kumpf  1.3             _magic = 0xDDDDDDDD;

116 mike   1.2     #endif
117                    }
118                
119                    /** Allows magic number to be used as a boolean expression. This function

120 kumpf  1.3             tests the magic number and return true if valid.

121 mike   1.2         */

122 kumpf  1.3         operator bool() const
123                    {

124 mike   1.2     #ifdef PEGASUS_DEBUG

125 kumpf  1.3             return _magic == MAGIC_NUMBER;

126 mike   1.2     #else

127 kumpf  1.3             return true;

128 mike   1.2     #endif
129                    }
130                
131                private:
132                    Uint32 _magic;
133                };
134                
135                PEGASUS_NAMESPACE_END
136                
137                #endif /* Pegasus_Magic_h */