1 // Copyright (c) 2014 OPEN CASCADE SAS
3 // This file is part of Open CASCADE Technology software library.
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.
11 // Alternatively, this file may be used under the terms of Open CASCADE
12 // commercial license or contractual agreement.
14 #ifndef _Standard_Handle_HeaderFile
15 #define _Standard_Handle_HeaderFile
17 #include <Standard_Address.hxx>
18 #include <Standard_Stream.hxx>
19 #include <Standard_Transient.hxx>
21 #include <type_traits>
23 class Standard_Transient;
25 namespace opencascade {
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> {};
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 {};
36 //! Intrusive smart pointer for use with Standard_Transient class and its descendants.
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.
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.
52 //! STL-compliant typedef of contained type
53 typedef T element_type;
58 handle () : entity(0) {}
60 //! Constructor from pointer to new object
61 handle (const T *thePtr) : entity(const_cast<T*>(thePtr))
67 handle (const handle& theHandle) : entity(theHandle.entity)
73 handle (handle&& theHandle) : entity(theHandle.entity)
84 //! Nullify the handle
90 //! Check for being null
91 bool IsNull() const { return entity == 0; }
93 //! Reset by new pointer
94 void reset (T* thePtr)
99 //! Assignment operator
100 handle& operator= (const handle& theHandle)
102 Assign (theHandle.entity);
106 //! Assignment to pointer
107 handle& operator= (const T* thePtr)
109 Assign (const_cast<T*>(thePtr));
114 handle& operator= (handle&& theHandle)
116 std::swap (this->entity, theHandle.entity);
120 //! STL-like cast to pointer to referred object
121 const T* get () const { return static_cast<const T*>(this->entity); }
123 //! STL-like cast to pointer to referred object
124 T* get () { return static_cast<T*>(this->entity); }
126 //! Member access operator (note non-const)
127 T* operator-> () const { return static_cast<T*>(this->entity); }
129 //! Dereferencing operator
130 T& operator* () { return *get(); }
132 //! Const dereferencing operator
133 const T& operator*() const { return *get(); }
135 //! Check for equality
137 bool operator== (const handle<T2>& theHandle) const
139 return get() == theHandle.get();
142 //! Check for equality
144 bool operator== (const T2 *thePtr) const
146 return get() == thePtr;
149 //! Check for equality
151 friend bool operator== (const T2 *left, const handle& right)
153 return left == right.get();
156 //! Check for inequality
158 bool operator!= (const handle<T2>& theHandle) const
160 return get() != theHandle.get();
163 //! Check for inequality
165 bool operator!= (const T2 *thePtr) const
167 return get() != thePtr;
170 //! Check for inequality
172 friend bool operator!= (const T2 *left, const handle& right)
174 return left != right.get();
177 //! Compare operator for possible use in std::map<> etc.
179 bool operator< (const handle<T2>& theHandle) const
181 return get() < theHandle.get();
184 //! Down casting operator from handle to base type
186 static typename std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type
187 DownCast (const handle<T2>& theObject)
189 return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
192 //! Down casting operator from pointer to base type
194 static typename std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type
195 DownCast (const T2* thePtr)
197 return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
200 //! For compatibility, define down casting operator from non-base type, as deprecated
202 Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
203 static handle DownCast (const handle<T2>& theObject, typename std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
205 return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
208 //! For compatibility, define down casting operator from non-base type, as deprecated
210 Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
211 static handle DownCast (const T2* thePtr, typename std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
213 return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
216 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1300) || \
217 (defined(_MSC_VER) && _MSC_VER >= 1800) || \
218 (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)))
220 //! Conversion to bool for use in conditional expressions
221 explicit operator bool () const
223 return entity != nullptr;
226 #else /* fallback version for compilers not supporting explicit conversion operators (VC10, VC11, GCC below 4.5) */
228 //! Conversion to bool-compatible type for use in conditional expressions
229 operator Standard_Transient* handle::* () const
231 return entity ? &handle::entity : 0;
236 // Support of conversions to handle of base type:
237 // - copy and move constructors and assignment operators if OCCT_HANDLE_NOCAST is defined
238 // - operators of upcast to const reference to base type otherwise
239 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1206) || \
240 (defined(_MSC_VER) && _MSC_VER >= 1800) || \
241 (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
243 #ifdef OCCT_HANDLE_NOCAST
245 //! Generalized copy constructor.
246 //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
247 template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
248 handle (const handle<T2>& theHandle) :
249 entity(theHandle.entity)
254 //! Generalized move constructor
255 template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
256 handle (handle<T2>&& theHandle)
257 : entity(theHandle.entity)
259 theHandle.entity = 0;
262 //! Generalized assignment operator
263 template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
264 handle operator = (const handle<T2>& theHandle)
266 Assign (theHandle.entity);
270 //! Generalized move operator
271 template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
272 handle& operator= (handle<T2>&& theHandle)
274 std::swap (this->entity, theHandle.entity);
280 //! Upcast to const reference to base type.
281 template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
282 operator const handle<T2>& () const
284 return reinterpret_cast<const handle<T2>&>(*this);
287 //! Upcast to non-const reference to base type.
288 //! NB: this cast can be dangerous, but required for legacy code; see #26377
289 template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
290 operator handle<T2>& ()
292 return reinterpret_cast<handle<T2>&>(*this);
295 #endif /* OCCT_HANDLE_NOCAST */
297 #else /* fallback version for compilers not supporting default arguments of function templates (VC10, VC11, GCC below 4.3) */
299 #ifdef OCCT_HANDLE_NOCAST
301 //! Generalized copy constructor.
302 //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
304 handle (const handle<T2>& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr) :
305 entity(theHandle.entity)
310 //! Generalized move constructor
312 handle (handle<T2>&& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr)
313 : entity(theHandle.entity)
315 theHandle.entity = 0;
318 //! Generalized assignment operator.
320 handle operator = (const handle<T2>& theHandle)
322 std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
323 (void)aTypeCheckHelperVar;
324 Assign (theHandle.entity);
328 //! Generalized move operator
330 handle& operator= (handle<T2>&& theHandle)
332 std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
333 (void)aTypeCheckHelperVar;
334 std::swap (this->entity, theHandle.entity);
340 //! Upcast to const reference to base type.
341 //! NB: this implementation will cause ambiguity errors on calls to overloaded
342 //! functions accepting handles to different types, since compatibility is
343 //! checked in the cast code rather than ensured by SFINAE (possible with C++11)
345 operator const handle<T2>& () const
347 // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
348 // (handle is being cast to const& to handle of non-base type)
349 return reinterpret_cast<typename std::enable_if<is_base_but_not_same<T2, T>::value, const handle<T2>&>::type>(*this);
352 //! Upcast to non-const reference to base type.
353 //! NB: this cast can be dangerous, but required for legacy code; see #26377
355 Standard_DEPRECATED("Passing non-const reference to handle of base type in function is unsafe; use variable of exact type")
356 operator handle<T2>& ()
358 // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
359 // (handle is being cast to const& to handle of non-base type)
360 return reinterpret_cast<typename std::enable_if<is_base_but_not_same<T2, T>::value, handle<T2>&>::type>(*this);
363 #endif /* OCCT_HANDLE_NOCAST */
365 #endif /* compiler switch */
370 void Assign (Standard_Transient *thePtr)
372 if (thePtr == entity)
379 //! Increment reference counter of referred object
383 entity->IncrementRefCounter();
386 //! Decrement reference counter and if 0, destroy referred object
389 if (entity != 0 && entity->DecrementRefCounter() == 0)
394 template <class T2> friend class handle;
397 Standard_Transient* entity;
400 } // namespace opencascade
402 //! Define Handle() macro
403 #define Handle(Class) opencascade::handle<Class>
405 //! Global method HashCode(), for use in hash maps
407 inline Standard_Integer HashCode (const Handle(T)& theHandle, const Standard_Integer theUpper)
409 return ::HashCode (const_cast<Standard_Address>(static_cast<const void*>(theHandle.get())), theUpper);
412 //! For compatibility with previous versions of OCCT, defines typedef opencascade::handle<Class> Handle(Class)
413 #define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; typedef Handle(C1) Handle_##C1;
414 #define DEFINE_STANDARD_HANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Transient)
415 #define DEFINE_STANDARD_PHANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Persistent)