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