src/Standard/Standard_Handle.hxx

   1 // Copyright (c) 2014 OPEN CASCADE SAS
   2 //
   3 // This file is part of Open CASCADE Technology software library.
   4 //
   5 // This library is free software; you can redistribute it and/or modify it under
   6 // the terms of the GNU Lesser General Public License version 2.1 as published
   7 // by the Free Software Foundation, with special exception defined in the file
   8 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
   9 // distribution for complete text of the license and disclaimer of any warranty.
  10 //
  11 // Alternatively, this file may be used under the terms of Open CASCADE
  12 // commercial license or contractual agreement.
  13
  14 #ifndef _Standard_Handle_HeaderFile
  15 #define _Standard_Handle_HeaderFile
  16
  17 #include <Standard_Address.hxx>
  18 #include <Standard_Stream.hxx>
  19 #include <Standard_Transient.hxx>
  20
  21 #include <type_traits>
  22
  23 class Standard_Transient;
  24
  25 namespace opencascade {
  26
  27   //! Intrusive smart pointer for use with Standard_Transient class and its descendants.
  28   //!
  29   //! This class is similar to boost::intrusive_ptr<>, with additional
  30   //! feature historically supported by Handles in OCCT:
  31   //! it has type conversion to const reference to handle to the base types,
  32   //! which allows it to be passed by reference
  33   //! in functions accepring reference to handle to base class.
  34   template <class T>
  35   class handle
  36   {
  37   public:
  38     //! STL-compliant typedef of contained type
  39     typedef T element_type;
  40
  41   public:
  42
  43     //! Empty constructor
  44     handle () : entity(0) {}
  45
  46     //! Constructor from pointer to new object
  47     handle (const T *thePtr) : entity(const_cast<T*>(thePtr))
  48     {
  49       BeginScope();
  50     }
  51 /* TODO: uncomment and remove const from method above
  52     //! Constructor from const pointer to new object;
  53     //! will raise exception if object's reference counter is zero
  54     explicit handle (const T *thePtr) : entity(thePtr->This())
  55     {
  56       BeginScope();
  57     }
  58 */
  59     //! Copy constructor
  60     handle (const handle& theHandle) : entity(theHandle.entity)
  61     {
  62       BeginScope();
  63     }
  64
  65     //! Destructor
  66     ~handle ()
  67     {
  68       EndScope();
  69     }
  70
  71     //! Nullify the handle
  72     void Nullify()
  73     {
  74       EndScope();
  75     }
  76
  77     //! Check for being null
  78     bool IsNull() const { return entity == 0; }
  79
  80     //! Reset by new pointer
  81     void reset (T* thePtr)
  82     {
  83       Assign (thePtr);
  84     }
  85
  86     //! Assignment operator
  87     handle& operator= (const handle& theHandle)
  88     {
  89       Assign (theHandle.entity);
  90       return *this;
  91     }
  92
  93     //! Assignment to pointer
  94     handle& operator= (const T* thePtr)
  95     {
  96       Assign (const_cast<T*>(thePtr));
  97       return *this;
  98     }
  99 /* uncomment along with constructor
 100     //! Assignment to pointer to const object
 101     handle& operator= (const T* thePtr)
 102     {
 103       Assign (thePtr->This());
 104       return *this;
 105     }
 106 */
 107     //! STL-like cast to pointer to referred object
 108     const T* get () const { return static_cast<const T*>(this->entity); }
 109
 110     //! STL-like cast to pointer to referred object
 111     T* get () { return static_cast<T*>(this->entity); }
 112
 113     //! Member access operator (note non-const)
 114     T* operator-> () const { return static_cast<T*>(this->entity); }
 115
 116     //! Dereferencing operator
 117     T& operator* () { return *get(); }
 118
 119     //! Const dereferencing operator
 120     const T& operator*() const { return *get(); }
 121
 122     //! Check for equality
 123     template <class T2>
 124     bool operator== (const handle<T2>& theHandle) const
 125     {
 126       return get() == theHandle.get();
 127     }
 128
 129     //! Check for equality
 130     template <class T2>
 131     bool operator== (const T2 *thePtr) const
 132     {
 133       return get() == thePtr;
 134     }
 135
 136     //! Check for equality
 137     template <class T2>
 138     friend bool operator== (const T2 *left, const handle& right)
 139     {
 140       return left == right.get();
 141     }
 142
 143     //! Check for inequality
 144     template <class T2>
 145     bool operator!= (const handle<T2>& theHandle) const
 146     {
 147       return get() != theHandle.get();
 148     }
 149
 150     //! Check for inequality
 151     template <class T2>
 152     bool operator!= (const T2 *thePtr) const
 153     {
 154       return get() != thePtr;
 155     }
 156
 157     //! Check for inequality
 158     template <class T2>
 159     friend bool operator!= (const T2 *left, const handle& right)
 160     {
 161       return left != right.get();
 162     }
 163
 164     //! Compare operator for possible use in std::map<> etc.
 165     template <class T2>
 166     bool operator< (const handle<T2>& theHandle) const
 167     {
 168       return get() < theHandle.get();
 169     }
 170
 171     //! Down casting operator
 172     template <class T2>
 173     static handle DownCast (const handle<T2>& theObject)
 174     {
 175       return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
 176     }
 177
 178     //! Down casting operator
 179     template <class T2>
 180     static handle DownCast (const T2* thePtr)
 181     {
 182       return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
 183     }
 184
 185 #if __cplusplus >= 201103L || (defined(_MSC_VER) && _MSC_VER >= 1800) || (defined(__GNUC__) && __GNUC__ >= 4 && __GNUC_MINOR__ >= 6)
 186
 187     //! Conversion to bool for use in conditional expressions
 188     explicit operator bool () const
 189     {
 190       return entity != nullptr;
 191     }
 192
 193 #else /* fallback version for compilers not supporting explicit conversion operators (VC10, VC11, GCC below 4.5) */
 194
 195     //! Conversion to bool-compatible type for use in conditional expressions
 196     operator Standard_Transient* handle::* () const
 197     {
 198       return entity ? &handle::entity : 0;
 199     }
 200
 201 #endif
 202
 203     //! Upcast to const reference to base type.
 204 #if __cplusplus >= 201103L || (defined(_MSC_VER) && _MSC_VER >= 1800) || (defined(__GNUC__) && __GNUC__ >= 4 && __GNUC_MINOR__ >= 3)
 205
 206     //! Upcast to const reference to base type.
 207     template <class T2, typename = typename std::enable_if<std::is_base_of<T2, T>::value>::type>
 208     operator const handle<T2>& () const
 209     {
 210       return reinterpret_cast<const handle<T2>&>(*this);
 211     }
 212
 213     //! Upcast to non-const reference to base type.
 214     //! NB: this cast can be dangerous, but required for legacy code; see #26377
 215     template <class T2, typename = typename std::enable_if<std::is_base_of<T2, T>::value>::type>
 216     operator handle<T2>& ()
 217     {
 218       return reinterpret_cast<handle<T2>&>(*this);
 219     }
 220
 221 #else /* fallback version for compilers not supporting default arguments of function templates (VC10, VC11, GCC below 4.3) */
 222
 223     //! Upcast to const reference to base type.
 224     //! NB: this implementation will cause ambiguity errors on calls to overloaded
 225     //! functions accepting handles to different types, since compatibility is
 226     //! checked in the cast code rather than ensured by SFINAE (possible with C++11)
 227     template <class T2>
 228     operator const handle<T2>& () const
 229     {
 230       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
 231       // (handle is being cast to const& to handle of non-base type)
 232       return reinterpret_cast<typename std::enable_if<std::is_base_of<T2, T>::value, const handle<T2>&>::type>(*this);
 233     }
 234
 235     //! Upcast to non-const reference to base type.
 236     //! NB: this cast can be dangerous, but required for legacy code; see #26377
 237     template <class T2>
 238     operator handle<T2>& ()
 239     {
 240       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
 241       // (handle is being cast to const& to handle of non-base type)
 242       return reinterpret_cast<typename std::enable_if<std::is_base_of<T2, T>::value, handle<T2>&>::type>(*this);
 243     }
 244
 245 #endif
 246
 247   private:
 248
 249     //! Assignment
 250     void Assign (Standard_Transient *thePtr)
 251     {
 252       if (thePtr == entity)
 253         return;
 254       EndScope();
 255       entity = thePtr;
 256       BeginScope();
 257     }
 258
 259     //! Increment reference counter of referred object
 260     void BeginScope()
 261     {
 262       if (entity != 0)
 263         entity->IncrementRefCounter();
 264     }
 265
 266     //! Decrement reference counter and if 0, destroy referred object
 267     void EndScope()
 268     {
 269       if (entity != 0 && entity->DecrementRefCounter() == 0)
 270         entity->Delete();
 271       entity = 0;
 272     }
 273
 274     template <class T2> friend class handle;
 275
 276   private:
 277     Standard_Transient* entity;
 278   };
 279
 280 } // namespace opencascade
 281
 282 //! Define Handle() macro
 283 #define Handle(Class) opencascade::handle<Class>
 284
 285 //! Global method HashCode(), for use in hash maps
 286 template <class T>
 287 inline Standard_Integer HashCode (const Handle(T)& theHandle, const Standard_Integer theUpper)
 288 {
 289   return ::HashCode (const_cast<Standard_Address>(static_cast<const void*>(theHandle.get())), theUpper);
 290 }
 291
 292 //! For compatibility with previous versions of OCCT, defines typedef opencascade::handle<Class> Handle(Class)
 293 #define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; typedef Handle(C1) Handle_##C1;
 294 #define DEFINE_STANDARD_HANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Transient)
 295 #define DEFINE_STANDARD_PHANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Persistent)
 296
 297 #endif