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