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   //! Trait yielding true if class T1 is base of T2 but not the same
  28   template <class T1, class T2, class Dummy = void>
  29   struct is_base_but_not_same : std::is_base_of <T1, T2> {};
  30
  31   //! Explicit specialization of is_base_of trait to workaround the
  32   //! requirement of type to be complete when T1 and T2 are the same.
  33   template <class T1, class T2>
  34   struct is_base_but_not_same <T1, T2, typename std::enable_if <std::is_same <T1, T2>::value>::type> : std::false_type {};
  35
  36   //! Intrusive smart pointer for use with Standard_Transient class and its descendants.
  37   //!
  38   //! This class is similar to boost::intrusive_ptr<>, with additional
  39   //! feature historically supported by Handles in OCCT:
  40   //! it has type conversion to const reference to handle to the base types,
  41   //! which allows it to be passed by reference
  42   //! in functions accepting reference to handle to base class.
  43   //!
  44   //! These casts (potentially unsafe) can be disabled by defining macro
  45   //! OCCT_HANDLE_NOCAST; if it is defined, generalized copy constructor
  46   //! and assignment operators are defined allowing to initialize handle
  47   //! of base type from handle to derived type.
  48   template <class T>
  49   class handle
  50   {
  51   public:
  52     //! STL-compliant typedef of contained type
  53     typedef T element_type;
  54
  55   public:
  56
  57     //! Empty constructor
  58     handle () : entity(0) {}
  59
  60     //! Constructor from pointer to new object
  61     handle (const T *thePtr) : entity(const_cast<T*>(thePtr))
  62     {
  63       BeginScope();
  64     }
  65
  66     //! Copy constructor
  67     handle (const handle& theHandle) : entity(theHandle.entity)
  68     {
  69       BeginScope();
  70     }
  71
  72     //! Move constructor
  73     handle (handle&& theHandle) : entity(theHandle.entity)
  74     {
  75       theHandle.entity = 0;
  76     }
  77
  78     //! Destructor
  79     ~handle ()
  80     {
  81       EndScope();
  82     }
  83
  84     //! Nullify the handle
  85     void Nullify()
  86     {
  87       EndScope();
  88     }
  89
  90     //! Check for being null
  91     bool IsNull() const { return entity == 0; }
  92
  93     //! Reset by new pointer
  94     void reset (T* thePtr)
  95     {
  96       Assign (thePtr);
  97     }
  98
  99     //! Assignment operator
 100     handle& operator= (const handle& theHandle)
 101     {
 102       Assign (theHandle.entity);
 103       return *this;
 104     }
 105
 106     //! Assignment to pointer
 107     handle& operator= (const T* thePtr)
 108     {
 109       Assign (const_cast<T*>(thePtr));
 110       return *this;
 111     }
 112
 113     //! Move operator
 114     handle& operator= (handle&& theHandle)
 115     {
 116       std::swap (this->entity, theHandle.entity);
 117       return *this;
 118     }
 119
 120     //! STL-like cast to pointer to referred object (note non-const).
 121     //! @sa std::shared_ptr::get()
 122     T* get() const { return static_cast<T*>(this->entity); }
 123
 124     //! Member access operator (note non-const)
 125     T* operator-> () const { return static_cast<T*>(this->entity); }
 126
 127     //! Dereferencing operator (note non-const)
 128     T& operator* () const { return *get(); }
 129
 130     //! Check for equality
 131     template <class T2>
 132     bool operator== (const handle<T2>& theHandle) const
 133     {
 134       return get() == theHandle.get();
 135     }
 136
 137     //! Check for equality
 138     template <class T2>
 139     bool operator== (const T2 *thePtr) const
 140     {
 141       return get() == thePtr;
 142     }
 143
 144     //! Check for equality
 145     template <class T2>
 146     friend bool operator== (const T2 *left, const handle& right)
 147     {
 148       return left == right.get();
 149     }
 150
 151     //! Check for inequality
 152     template <class T2>
 153     bool operator!= (const handle<T2>& theHandle) const
 154     {
 155       return get() != theHandle.get();
 156     }
 157
 158     //! Check for inequality
 159     template <class T2>
 160     bool operator!= (const T2 *thePtr) const
 161     {
 162       return get() != thePtr;
 163     }
 164
 165     //! Check for inequality
 166     template <class T2>
 167     friend bool operator!= (const T2 *left, const handle& right)
 168     {
 169       return left != right.get();
 170     }
 171
 172     //! Compare operator for possible use in std::map<> etc.
 173     template <class T2>
 174     bool operator< (const handle<T2>& theHandle) const
 175     {
 176       return get() < theHandle.get();
 177     }
 178
 179     //! Down casting operator from handle to base type
 180     template <class T2>
 181     static typename std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type
 182       DownCast (const handle<T2>& theObject)
 183     {
 184       return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
 185     }
 186
 187     //! Down casting operator from pointer to base type
 188     template <class T2>
 189     static typename std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type
 190       DownCast (const T2* thePtr)
 191     {
 192       return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
 193     }
 194
 195     //! For compatibility, define down casting operator from non-base type, as deprecated
 196     template <class T2>
 197     Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
 198     static handle DownCast (const handle<T2>& theObject, typename std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
 199     {
 200       return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
 201     }
 202
 203     //! For compatibility, define down casting operator from non-base type, as deprecated
 204     template <class T2>
 205     Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
 206     static handle DownCast (const T2* thePtr, typename std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
 207     {
 208       return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
 209     }
 210
 211 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1300) || \
 212     (defined(_MSC_VER) && _MSC_VER >= 1800) || \
 213     (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)))
 214
 215     //! Conversion to bool for use in conditional expressions
 216     explicit operator bool () const
 217     {
 218       return entity != nullptr;
 219     }
 220
 221 #else /* fallback version for compilers not supporting explicit conversion operators (VC10, VC11, GCC below 4.5) */
 222
 223     //! Conversion to bool-compatible type for use in conditional expressions
 224     operator Standard_Transient* handle::* () const
 225     {
 226       return entity ? &handle::entity : 0;
 227     }
 228
 229 #endif
 230
 231     // Support of conversions to handle of base type:
 232     // - copy and move constructors and assignment operators if OCCT_HANDLE_NOCAST is defined
 233     // - operators of upcast to const reference to base type otherwise
 234 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1206) || \
 235     (defined(_MSC_VER) && _MSC_VER >= 1800) || \
 236     (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
 237
 238 #ifdef OCCT_HANDLE_NOCAST
 239
 240     //! Generalized copy constructor.
 241     //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
 242     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
 243     handle (const handle<T2>& theHandle) :
 244       entity(theHandle.entity)
 245     {
 246       BeginScope();
 247     }
 248
 249     //! Generalized move constructor
 250     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
 251     handle (handle<T2>&& theHandle)
 252       : entity(theHandle.entity)
 253     {
 254       theHandle.entity = 0;
 255     }
 256
 257     //! Generalized assignment operator
 258     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
 259     handle operator = (const handle<T2>& theHandle)
 260     {
 261       Assign (theHandle.entity);
 262       return *this;
 263     }
 264
 265     //! Generalized move operator
 266     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
 267     handle& operator= (handle<T2>&& theHandle)
 268     {
 269       std::swap (this->entity, theHandle.entity);
 270       return *this;
 271     }
 272
 273 #else
 274
 275     //! Upcast to const reference to base type.
 276     template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
 277     operator const handle<T2>& () const
 278     {
 279       return reinterpret_cast<const handle<T2>&>(*this);
 280     }
 281
 282     //! Upcast to non-const reference to base type.
 283     //! NB: this cast can be dangerous, but required for legacy code; see #26377
 284     template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
 285     operator handle<T2>& ()
 286     {
 287       return reinterpret_cast<handle<T2>&>(*this);
 288     }
 289
 290 #endif /* OCCT_HANDLE_NOCAST */
 291
 292 #else /* fallback version for compilers not supporting default arguments of function templates (VC10, VC11, GCC below 4.3) */
 293
 294 #ifdef OCCT_HANDLE_NOCAST
 295
 296     //! Generalized copy constructor.
 297     //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
 298     template <class T2>
 299     handle (const handle<T2>& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr) :
 300       entity(theHandle.entity)
 301     {
 302       BeginScope();
 303     }
 304
 305     //! Generalized move constructor
 306     template <class T2>
 307     handle (handle<T2>&& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr)
 308       : entity(theHandle.entity)
 309     {
 310       theHandle.entity = 0;
 311     }
 312
 313     //! Generalized assignment operator.
 314     template <class T2>
 315     handle operator = (const handle<T2>& theHandle)
 316     {
 317       std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
 318       (void)aTypeCheckHelperVar;
 319       Assign (theHandle.entity);
 320       return *this;
 321     }
 322
 323     //! Generalized move operator
 324     template <class T2>
 325     handle& operator= (handle<T2>&& theHandle)
 326     {
 327       std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
 328       (void)aTypeCheckHelperVar;
 329       std::swap (this->entity, theHandle.entity);
 330       return *this;
 331     }
 332
 333 #else
 334
 335     //! Upcast to const reference to base type.
 336     //! NB: this implementation will cause ambiguity errors on calls to overloaded
 337     //! functions accepting handles to different types, since compatibility is
 338     //! checked in the cast code rather than ensured by SFINAE (possible with C++11)
 339     template <class T2>
 340     operator const handle<T2>& () const
 341     {
 342       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
 343       // (handle is being cast to const& to handle of non-base type)
 344       return reinterpret_cast<typename std::enable_if<is_base_but_not_same<T2, T>::value, const handle<T2>&>::type>(*this);
 345     }
 346
 347     //! Upcast to non-const reference to base type.
 348     //! NB: this cast can be dangerous, but required for legacy code; see #26377
 349     template <class T2>
 350     Standard_DEPRECATED("Passing non-const reference to handle of base type in function is unsafe; use variable of exact type")
 351     operator handle<T2>& ()
 352     {
 353       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
 354       // (handle is being cast to const& to handle of non-base type)
 355       return reinterpret_cast<typename std::enable_if<is_base_but_not_same<T2, T>::value, handle<T2>&>::type>(*this);
 356     }
 357
 358 #endif /* OCCT_HANDLE_NOCAST */
 359
 360 #endif /* compiler switch */
 361
 362   private:
 363
 364     //! Assignment
 365     void Assign (Standard_Transient *thePtr)
 366     {
 367       if (thePtr == entity)
 368         return;
 369       EndScope();
 370       entity = thePtr;
 371       BeginScope();
 372     }
 373
 374     //! Increment reference counter of referred object
 375     void BeginScope()
 376     {
 377       if (entity != 0)
 378         entity->IncrementRefCounter();
 379     }
 380
 381     //! Decrement reference counter and if 0, destroy referred object
 382     void EndScope()
 383     {
 384       if (entity != 0 && entity->DecrementRefCounter() == 0)
 385         entity->Delete();
 386       entity = 0;
 387     }
 388
 389     template <class T2> friend class handle;
 390
 391   private:
 392     Standard_Transient* entity;
 393   };
 394
 395 } // namespace opencascade
 396
 397 //! Define Handle() macro
 398 #define Handle(Class) opencascade::handle<Class>
 399
 400 //! Global method HashCode(), for use in hash maps
 401 template <class T>
 402 inline Standard_Integer HashCode (const Handle(T)& theHandle, const Standard_Integer theUpper)
 403 {
 404   return ::HashCode (const_cast<Standard_Address>(static_cast<const void*>(theHandle.get())), theUpper);
 405 }
 406
 407 //! For compatibility with previous versions of OCCT, define Handle_Class alias for opencascade::handle<Class>.
 408 #if (defined(_MSC_VER) && _MSC_VER >= 1800)
 409 //! For Visual Studio 2013+, define Handle_Class as non-template class to allow exporting this type in C++/CLI.
 410 #define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; class Handle_##C1 : public Handle(C1) \
 411 { \
 412 public: \
 413   Handle_##C1() {} \
 414   Handle_##C1(Handle(C1)&& theHandle) : Handle(C1)(theHandle) {} \
 415   template <class T2, typename = typename std::enable_if <std::is_base_of <C1,T2>::value>::type> \
 416   inline Handle_##C1(const opencascade::handle<T2>& theOther) : Handle(C1)(theOther) {} \
 417   template <class T2, typename = typename std::enable_if <std::is_base_of <C1,T2>::value>::type> \
 418   inline Handle_##C1(const T2* theOther) : Handle(C1)(theOther) {} \
 419   template<typename T> inline Handle_##C1& operator=(T theOther) { Handle(C1)::operator=(theOther); return *this; } \
 420 };
 421 #else
 422 //! For other compilers, use simple typedef
 423 #define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; typedef Handle(C1) Handle_##C1;
 424 #endif
 425
 426 #define DEFINE_STANDARD_HANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Transient)
 427 #define DEFINE_STANDARD_PHANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Persistent)
 428
 429 #endif