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