classapi.h

Go to the documentation of this file.

/////////////////////////////////////////////////////////////////////////////////////////
/// \file classapi.h  
/// \brief Header file that defines templatized utility functions used to implement
///        the private data management inside the atomic classes
///
/// Functions to:
/// - set the private data
/// - retrieve the private data
/// - deallocate the private data
///
/// Each utility function comes in 2 flavors:
/// - for the SPARK::TObject instance as accessed from an instance callback
/// - for the SPARK::TInverse instance as accessed from a static callback
///
/// Also, the DeleteData() functions are parameterized with a delete policy type that
/// lets you implement the deletion task. We have provided two such policy classes:
/// - SPARK::delete_policy 
/// - SPARK::delete_array_policy
///
/////////////////////////////////////////////////////////////////////////////////////////
///
/// \author  Dimitri Curtil
/// \version %SPARK 2.0
/// \date    April 16, 2003
///
/////////////////////////////////////////////////////////////////////////////////////////
/// \attention
/// PORTIONS COPYRIGHT (C) 2003 AYRES SOWELL ASSOCIATES, INC. \n
/// PORTIONS COPYRIGHT (C) 2003 THE REGENTS OF THE UNIVERSITY OF CALIFORNIA .
///   PENDING APPROVAL BY THE US DEPARTMENT OF ENERGY. ALL RIGHTS RESERVED.
///
/////////////////////////////////////////////////////////////////////////////////////////


#if !defined(__CLASSAPI_H__)
#define __CLASSAPI_H__


#include "compat.h"


/////////////////////////////////////////////////////////////////////////////////////////
/// \namespace SPARK::AtomicClass
/// \brief Definition of the atomic class API library used to manage the private data
///        from the callbacks asociated with each SPARK::TObject and SPARK::TInverse 
///        instances.
/////////////////////////////////////////////////////////////////////////////////////////

namespace SPARK { 
        
        // Forward declaration
        class TObject;
        class TInverse;
         
        
        /// \struct delete_policy
        /// \brief  Policy class used to delete non-array data types using delete operator
        ///
        /// \note The static method apply() does not throw any exceptions.
        struct delete_policy {
                template<typename DataType>
                static bool apply(DataType* data) SPARK_NOT_THROWING
                { 
                        try {
                                delete data;
                        }
                        catch(...) {
                                return false;
                        }
                        return true;
                }
        };


        /// \struct delete_array_policy
        /// \brief  Policy class used to delete array data types using delete [] operator
        ///
        /// \note The static method apply() does not throw any exceptions.
        struct delete_array_policy {
                template<typename DataType>
                static bool apply(DataType* data) SPARK_NOT_THROWING
                { 
                        try {
                                delete [] data;
                        }
                        catch(...) {
                                return false;
                        }
                        return true;
                }
        };

        
        /// \struct deleter
        /// \brief  Helper class that implements either delete_policy or delete_array_policy
        ///         depending on the compile-time value of the non-type parameter IsArray
        ///
        /// The delete policy is used in the SPARK::AtomicClass::DeleteData() API function.
        /// Also see macro #DELETE_DATA in file spark.h for usage of the deleter<> struct. 
        template<bool IsArray>
        struct deleter 
        {};

        template<> // IsArray = false
        struct deleter<false> : public delete_policy
        {};

        template<> // IsArray = true
        struct deleter<true> : public delete_array_policy
        {};




        namespace AtomicClass {

        /// \brief Sets pointer to private data in TObject instance
        /// 
        /// \param object  Address of the TObject instance (use THIS macro from within the callback body)
        /// \param data    Address of the private data to be stored within the TObject instance
        template<typename DataType>
        void SetData(TObject* object, DataType* data)
        {
                object->SetData( data );
        }

        
        /// \brief Sets pointer to static private data in TInverse instance
        /// 
        /// \param inverse     Address of the TInverse instance (use THIS macro from within the static callback body)
        /// \param staticData  Address of the static private data to be stored within the TInverse instance
        template<typename StaticDataType>
        void SetData(TInverse* inverse, StaticDataType* staticData)
        {
                inverse->SetStaticData( staticData );
        }

        
        /// \brief Returns address of private data of type \c DataType attached to the \c TObject instance
        ///
        /// \return Pointer to private data as DataType*
        /// \param  object (use THIS macro from within the callback body)
        template<typename DataType>
        DataType* GetData(TObject* object)
        {
                return static_cast<DataType*>( object->GetData() );
        }


        /// \brief Returns address of static private data of type \c StaticDataType attached to the \c TInverse instance
        ///
        /// \return Pointer to static private data as StaticDataType*
        /// \param inverse (use THIS macro from within the static callback body)
        template<typename StaticDataType>
        StaticDataType* GetData(TInverse* inverse)
        {
                return static_cast<StaticDataType*>( inverse->GetStaticData() );
        }

        
        /// \brief Deallocates private data of type \c DataType attached to a TObject instance
        ///
        /// \param  object  Address of the TObject instance (use THIS macro from within the callback body)
        /// \param  dummy1   Never specify this parameter. It is used as a workaround for a bug in MSVC++
        /// \param  dummy2   Never specify this parameter. It is used as a workaround for a bug in MSVC++
        ///
        /// \pre  DeletePolicyType must define a static method named apply() that performs the deletion task.
        ///       Possible policy candidates are: SPARK::delete_policy and SPARK::delete_array_policy
        /// \post Private data is deallocated and pointer in TObject instance is reset to 0
        ///
        // \bug  MSVC++ does not overload normal functions depending on explicit argument specifications
        //       (see Microsoft KB Article 240871). The workaround consists in adding a dummy parameter 
        //       with proper default value.
        template<typename DataType, typename DeletePolicyType>
        bool DeleteData(TObject* object, DataType* dummy1 = 0, DeletePolicyType* dummy2 = 0)
        {
                // Cast void* to private data type
                // \bug MSVC++ does not recognize template type from return type. It is therefore explictly specified.
                DataType* Data = SPARK::AtomicClass::GetData<DataType>( object );

                // Release allocated memory
                bool Deleted = DeletePolicyType::apply( Data );

                // Reset NULL pointer to private data
                // \bug MSVC++ cannot deduce template type of argument. It is therefore explictly specified.
                SPARK::AtomicClass::SetData<DataType>( object, 0 );

                return Deleted;
        }


        /// \brief Deallocates private data of type \c StaticDataType attached to a TInverse instance
        ///
        /// \param  inverse  Address of the TInverse instance (use THIS macro from within the static callback body)
        /// \param  dummy1   Never specify this parameter. It is used as a workaround for a bug in MSVC++
        /// \param  dummy2   Never specify this parameter. It is used as a workaround for a bug in MSVC++
        ///
        /// \pre  DeletePolicyType must define a static method named apply() that performs the deletion task.
        ///       Possible policy candidates are: SPARK::delete_policy and SPARK::delete_array_policy
        /// \post Private data is deallocated and pointer in TInverse instance is reset to 0
        ///
        // \bug  MSVC++ does not overload normal functions depending on explicit argument specifications
        //       (see Microsoft KB Article 240871). The workaround consists in adding a dummy parameter 
        //       with proper default value.
        template<typename StaticDataType, typename DeletePolicyType>
        bool DeleteData(TInverse* inverse, StaticDataType* dummy1 = 0, DeletePolicyType* dummy2 = 0)
        {
                // Cast void* to private data type
                // \bug MS VC++ does not recognize template type from return type. It is therefore explictly specified.
                StaticDataType* StaticData = SPARK::AtomicClass::GetData<StaticDataType>( inverse );

                // Release allocated memory
                bool Deleted = DeletePolicyType::apply( StaticData );

                // Reset NULL pointer to private data
                // \bug MSVC++ cannot deduce template type of argument. It is therefore explictly specified.
                SPARK::AtomicClass::SetData<StaticDataType>( inverse, 0 );

                return Deleted;
        }


}; }; // namespace SPARK::AtomicClass
/////////////////////////////////////////////////////////////////////////////////////////


#endif //__CLASSAPI_H__

---