0030679: Attached model hangs most of OCCT common functionality
[occt.git] / src / Standard / Standard_Handle.hxx
CommitLineData
e7195ab4 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>
2b2be3fb 18#include <Standard_Std.hxx>
e7195ab4 19#include <Standard_Stream.hxx>
20#include <Standard_Transient.hxx>
21
e7195ab4 22class Standard_Transient;
23
71c810df 24//! Namespace opencascade is intended for low-level template classes and functions
e7195ab4 25namespace opencascade {
26
27 //! Intrusive smart pointer for use with Standard_Transient class and its descendants.
28 //!
1aa738dd
BB
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).
4796758e 37 //!
1aa738dd
BB
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.
4796758e 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.
1aa738dd
BB
47 //!
48 //! Weak pointers are not supported.
e7195ab4 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 }
4796758e 66
e7195ab4 67 //! Copy constructor
68 handle (const handle& theHandle) : entity(theHandle.entity)
69 {
70 BeginScope();
71 }
72
77bc2ad1 73#ifndef OCCT_NO_RVALUE_REFERENCE
5d351a08 74 //! Move constructor
75 handle (handle&& theHandle) : entity(theHandle.entity)
76 {
77 theHandle.entity = 0;
78 }
71c810df 79#endif
5d351a08 80
e7195ab4 81 //! Destructor
82 ~handle ()
83 {
84 EndScope();
85 }
86
87 //! Nullify the handle
88 void Nullify()
89 {
90 EndScope();
91 }
92
93 //! Check for being null
94 bool IsNull() const { return entity == 0; }
95
96 //! Reset by new pointer
97 void reset (T* thePtr)
98 {
99 Assign (thePtr);
100 }
101
102 //! Assignment operator
103 handle& operator= (const handle& theHandle)
104 {
105 Assign (theHandle.entity);
106 return *this;
107 }
108
109 //! Assignment to pointer
110 handle& operator= (const T* thePtr)
111 {
112 Assign (const_cast<T*>(thePtr));
113 return *this;
114 }
4796758e 115
77bc2ad1 116#ifndef OCCT_NO_RVALUE_REFERENCE
5d351a08 117 //! Move operator
118 handle& operator= (handle&& theHandle)
119 {
120 std::swap (this->entity, theHandle.entity);
121 return *this;
122 }
71c810df 123#endif
5d351a08 124
9016c8bd 125 //! STL-like cast to pointer to referred object (note non-const).
126 //! @sa std::shared_ptr::get()
127 T* get() const { return static_cast<T*>(this->entity); }
e7195ab4 128
129 //! Member access operator (note non-const)
130 T* operator-> () const { return static_cast<T*>(this->entity); }
131
9016c8bd 132 //! Dereferencing operator (note non-const)
133 T& operator* () const { return *get(); }
e7195ab4 134
135 //! Check for equality
136 template <class T2>
137 bool operator== (const handle<T2>& theHandle) const
138 {
e8862cf4 139 return get() == theHandle.get();
e7195ab4 140 }
141
142 //! Check for equality
e8862cf4 143 template <class T2>
144 bool operator== (const T2 *thePtr) const
e7195ab4 145 {
e8862cf4 146 return get() == thePtr;
e7195ab4 147 }
148
149 //! Check for equality
e8862cf4 150 template <class T2>
151 friend bool operator== (const T2 *left, const handle& right)
e7195ab4 152 {
e8862cf4 153 return left == right.get();
e7195ab4 154 }
155
156 //! Check for inequality
157 template <class T2>
158 bool operator!= (const handle<T2>& theHandle) const
159 {
e8862cf4 160 return get() != theHandle.get();
e7195ab4 161 }
162
163 //! Check for inequality
e8862cf4 164 template <class T2>
165 bool operator!= (const T2 *thePtr) const
e7195ab4 166 {
e8862cf4 167 return get() != thePtr;
e7195ab4 168 }
169
170 //! Check for inequality
e8862cf4 171 template <class T2>
172 friend bool operator!= (const T2 *left, const handle& right)
e7195ab4 173 {
e8862cf4 174 return left != right.get();
e7195ab4 175 }
176
d1a67b9d 177 //! Compare operator for possible use in std::map<> etc.
178 template <class T2>
179 bool operator< (const handle<T2>& theHandle) const
180 {
181 return get() < theHandle.get();
182 }
183
a9dde4a3 184 //! Down casting operator from handle to base type
e7195ab4 185 template <class T2>
71c810df 186 static typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type
a9dde4a3 187 DownCast (const handle<T2>& theObject)
e7195ab4 188 {
189 return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
190 }
191
a9dde4a3 192 //! Down casting operator from pointer to base type
e7195ab4 193 template <class T2>
71c810df 194 static typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, handle>::type
a9dde4a3 195 DownCast (const T2* thePtr)
196 {
197 return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
198 }
199
200 //! For compatibility, define down casting operator from non-base type, as deprecated
201 template <class T2>
202 Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
71c810df 203 static handle DownCast (const handle<T2>& theObject, typename opencascade::std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
a9dde4a3 204 {
205 return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
206 }
207
208 //! For compatibility, define down casting operator from non-base type, as deprecated
209 template <class T2>
210 Standard_DEPRECATED("down-casting from object of the same or unrelated type is meaningless")
71c810df 211 static handle DownCast (const T2* thePtr, typename opencascade::std::enable_if<!is_base_but_not_same<T2, T>::value, void*>::type = 0)
e7195ab4 212 {
213 return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
214 }
215
d9e90905 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)))
d1a67b9d 219
220 //! Conversion to bool for use in conditional expressions
221 explicit operator bool () const
222 {
223 return entity != nullptr;
224 }
225
226#else /* fallback version for compilers not supporting explicit conversion operators (VC10, VC11, GCC below 4.5) */
227
228 //! Conversion to bool-compatible type for use in conditional expressions
229 operator Standard_Transient* handle::* () const
230 {
231 return entity ? &handle::entity : 0;
232 }
233
234#endif
235
4796758e 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
d9e90905 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)))
e7195ab4 242
4796758e 243#ifdef OCCT_HANDLE_NOCAST
244
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)
250 {
251 BeginScope();
252 }
253
5d351a08 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)
258 {
259 theHandle.entity = 0;
260 }
261
4796758e 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)
265 {
266 Assign (theHandle.entity);
267 return *this;
268 }
269
5d351a08 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)
273 {
274 std::swap (this->entity, theHandle.entity);
275 return *this;
276 }
277
4796758e 278#else
279
e7195ab4 280 //! Upcast to const reference to base type.
4796758e 281 template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
e7195ab4 282 operator const handle<T2>& () const
283 {
284 return reinterpret_cast<const handle<T2>&>(*this);
285 }
286
287 //! Upcast to non-const reference to base type.
d1a67b9d 288 //! NB: this cast can be dangerous, but required for legacy code; see #26377
4796758e 289 template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
e7195ab4 290 operator handle<T2>& ()
291 {
292 return reinterpret_cast<handle<T2>&>(*this);
293 }
294
4796758e 295#endif /* OCCT_HANDLE_NOCAST */
296
e7195ab4 297#else /* fallback version for compilers not supporting default arguments of function templates (VC10, VC11, GCC below 4.3) */
298
4796758e 299#ifdef OCCT_HANDLE_NOCAST
300
301 //! Generalized copy constructor.
302 //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
303 template <class 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)
306 {
307 BeginScope();
308 }
309
77bc2ad1 310#ifndef OCCT_NO_RVALUE_REFERENCE
5d351a08 311 //! Generalized move constructor
312 template <class T2>
313 handle (handle<T2>&& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr)
314 : entity(theHandle.entity)
315 {
316 theHandle.entity = 0;
317 }
71c810df 318#endif
5d351a08 319
4796758e 320 //! Generalized assignment operator.
321 template <class T2>
322 handle operator = (const handle<T2>& theHandle)
323 {
324 std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
325 (void)aTypeCheckHelperVar;
326 Assign (theHandle.entity);
327 return *this;
328 }
329
77bc2ad1 330#ifndef OCCT_NO_RVALUE_REFERENCE
5d351a08 331 //! Generalized move operator
332 template <class T2>
333 handle& operator= (handle<T2>&& theHandle)
334 {
335 std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
336 (void)aTypeCheckHelperVar;
337 std::swap (this->entity, theHandle.entity);
338 return *this;
339 }
71c810df 340#endif
5d351a08 341
4796758e 342#else
343
e7195ab4 344 //! Upcast to const reference to base type.
345 //! NB: this implementation will cause ambiguity errors on calls to overloaded
346 //! functions accepting handles to different types, since compatibility is
347 //! checked in the cast code rather than ensured by SFINAE (possible with C++11)
348 template <class T2>
349 operator const handle<T2>& () const
350 {
351 // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
352 // (handle is being cast to const& to handle of non-base type)
71c810df 353 return reinterpret_cast<typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, const handle<T2>&>::type>(*this);
e7195ab4 354 }
355
356 //! Upcast to non-const reference to base type.
d1a67b9d 357 //! NB: this cast can be dangerous, but required for legacy code; see #26377
e7195ab4 358 template <class T2>
aa00364d 359 Standard_DEPRECATED("Passing non-const reference to handle of base type in function is unsafe; use variable of exact type")
e7195ab4 360 operator handle<T2>& ()
361 {
362 // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
363 // (handle is being cast to const& to handle of non-base type)
71c810df 364 return reinterpret_cast<typename opencascade::std::enable_if<is_base_but_not_same<T2, T>::value, handle<T2>&>::type>(*this);
e7195ab4 365 }
366
4796758e 367#endif /* OCCT_HANDLE_NOCAST */
368
369#endif /* compiler switch */
e7195ab4 370
371 private:
372
373 //! Assignment
374 void Assign (Standard_Transient *thePtr)
375 {
376 if (thePtr == entity)
377 return;
378 EndScope();
379 entity = thePtr;
380 BeginScope();
381 }
382
383 //! Increment reference counter of referred object
384 void BeginScope()
385 {
386 if (entity != 0)
387 entity->IncrementRefCounter();
388 }
389
390 //! Decrement reference counter and if 0, destroy referred object
391 void EndScope()
392 {
393 if (entity != 0 && entity->DecrementRefCounter() == 0)
394 entity->Delete();
395 entity = 0;
396 }
397
398 template <class T2> friend class handle;
399
400 private:
401 Standard_Transient* entity;
402 };
403
404} // namespace opencascade
405
406//! Define Handle() macro
407#define Handle(Class) opencascade::handle<Class>
408
2b2be3fb 409//! Computes a hash code for the standard handle, in the range [1, theUpperBound]
410//! @param TheTransientType the type of the object the handle is referred to
411//! @param theHandle the standard handle which hash code is to be computed
412//! @param theUpperBound the upper bound of the range a computing hash code must be within
413//! @return a computed hash code, in the range [1, theUpperBound]
414template <class TheTransientType>
415Standard_Integer HashCode (const Handle (TheTransientType) & theHandle, const Standard_Integer theUpperBound)
e7195ab4 416{
2b2be3fb 417 return ::HashCode (theHandle.get(), theUpperBound);
e7195ab4 418}
419
a13f2dc4 420//! For compatibility with previous versions of OCCT, define Handle_Class alias for opencascade::handle<Class>.
421#if (defined(_MSC_VER) && _MSC_VER >= 1800)
422//! For Visual Studio 2013+, define Handle_Class as non-template class to allow exporting this type in C++/CLI.
423#define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; class Handle_##C1 : public Handle(C1) \
424{ \
425public: \
426 Handle_##C1() {} \
427 Handle_##C1(Handle(C1)&& theHandle) : Handle(C1)(theHandle) {} \
428 template <class T2, typename = typename std::enable_if <std::is_base_of <C1,T2>::value>::type> \
429 inline Handle_##C1(const opencascade::handle<T2>& theOther) : Handle(C1)(theOther) {} \
430 template <class T2, typename = typename std::enable_if <std::is_base_of <C1,T2>::value>::type> \
431 inline Handle_##C1(const T2* theOther) : Handle(C1)(theOther) {} \
432 template<typename T> inline Handle_##C1& operator=(T theOther) { Handle(C1)::operator=(theOther); return *this; } \
433};
434#else
435//! For other compilers, use simple typedef
d1a67b9d 436#define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; typedef Handle(C1) Handle_##C1;
a13f2dc4 437#endif
438
e7195ab4 439#define DEFINE_STANDARD_HANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Transient)
440#define DEFINE_STANDARD_PHANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Persistent)
441
442#endif