0026549: Provide move constructors and operators for basic classes
[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<>, 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.
43   //!
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   template <class T>
49   class handle
50   {
51   public:
52     //! STL-compliant typedef of contained type
53     typedef T element_type;
54
55   public:
56   
57     //! Empty constructor
58     handle () : entity(0) {}
59
60     //! Constructor from pointer to new object
61     handle (const T *thePtr) : entity(const_cast<T*>(thePtr))
62     {
63       BeginScope();
64     }
65
66     //! Copy constructor
67     handle (const handle& theHandle) : entity(theHandle.entity)
68     {
69       BeginScope();
70     }
71
72     //! Move constructor
73     handle (handle&& theHandle) : entity(theHandle.entity)
74     {
75       theHandle.entity = 0;
76     }
77
78     //! Destructor
79     ~handle ()
80     {
81       EndScope();
82     }
83
84     //! Nullify the handle
85     void Nullify()
86     {
87       EndScope();
88     }
89
90     //! Check for being null
91     bool IsNull() const { return entity == 0; } 
92
93     //! Reset by new pointer
94     void reset (T* thePtr)
95     {
96       Assign (thePtr);
97     }
98
99     //! Assignment operator
100     handle& operator= (const handle& theHandle)
101     {
102       Assign (theHandle.entity);
103       return *this;
104     }
105
106     //! Assignment to pointer
107     handle& operator= (const T* thePtr)
108     {
109       Assign (const_cast<T*>(thePtr));
110       return *this;
111     }
112
113     //! Move operator
114     handle& operator= (handle&& theHandle)
115     {
116       std::swap (this->entity, theHandle.entity);
117       return *this;
118     }
119
120     //! STL-like cast to pointer to referred object
121     const T* get () const { return static_cast<const T*>(this->entity); }
122
123     //! STL-like cast to pointer to referred object
124     T* get () { 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
130     T& operator* () { return *get(); }
131
132     //! Const dereferencing operator
133     const T& operator*() const { return *get(); }
134
135     //! Check for equality
136     template <class T2>
137     bool operator== (const handle<T2>& theHandle) const
138     { 
139       return get() == theHandle.get();
140     }
141
142     //! Check for equality
143     template <class T2>
144     bool operator== (const T2 *thePtr) const
145     { 
146       return get() == thePtr;
147     }
148
149     //! Check for equality
150     template <class T2>
151     friend bool operator== (const T2 *left, const handle& right)
152     {
153       return left == right.get();
154     }
155
156     //! Check for inequality
157     template <class T2>
158     bool operator!= (const handle<T2>& theHandle) const
159     {
160       return get() != theHandle.get();
161     }
162
163     //! Check for inequality
164     template <class T2>
165     bool operator!= (const T2 *thePtr) const
166     {
167       return get() != thePtr;
168     }
169
170     //! Check for inequality
171     template <class T2>
172     friend bool operator!= (const T2 *left, const handle& right)
173     {
174       return left != right.get();
175     }
176
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
184     //! Down casting operator
185     template <class T2>
186     static handle DownCast (const handle<T2>& theObject)
187     {
188       return handle (dynamic_cast<T*>(const_cast<T2*>(theObject.get())));
189     }
190
191     //! Down casting operator
192     template <class T2>
193     static handle DownCast (const T2* thePtr)
194     {
195       return handle (dynamic_cast<T*>(const_cast<T2*>(thePtr)));
196     }
197
198 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1300) || \
199     (defined(_MSC_VER) && _MSC_VER >= 1800) || \
200     (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6)))
201
202     //! Conversion to bool for use in conditional expressions
203     explicit operator bool () const
204     { 
205       return entity != nullptr;
206     }
207
208 #else /* fallback version for compilers not supporting explicit conversion operators (VC10, VC11, GCC below 4.5) */
209
210     //! Conversion to bool-compatible type for use in conditional expressions
211     operator Standard_Transient* handle::* () const
212     { 
213       return entity ? &handle::entity : 0;
214     }
215
216 #endif
217
218     // Support of conversions to handle of base type:
219     // - copy and move constructors and assignment operators if OCCT_HANDLE_NOCAST is defined
220     // - operators of upcast to const reference to base type otherwise
221 #if (defined(__clang__)) || (defined(__INTEL_COMPILER) && __INTEL_COMPILER >= 1206) || \
222     (defined(_MSC_VER) && _MSC_VER >= 1800) || \
223     (defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)))
224
225 #ifdef OCCT_HANDLE_NOCAST
226
227     //! Generalized copy constructor.
228     //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
229     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
230     handle (const handle<T2>& theHandle) :
231       entity(theHandle.entity)
232     {
233       BeginScope();
234     }
235
236     //! Generalized move constructor
237     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
238     handle (handle<T2>&& theHandle)
239       : entity(theHandle.entity)
240     {
241       theHandle.entity = 0;
242     }
243
244     //! Generalized assignment operator
245     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
246     handle operator = (const handle<T2>& theHandle)
247     {
248       Assign (theHandle.entity);
249       return *this;
250     }
251
252     //! Generalized move operator
253     template <class T2, typename = typename std::enable_if <is_base_but_not_same <T, T2>::value>::type>
254     handle& operator= (handle<T2>&& theHandle)
255     {
256       std::swap (this->entity, theHandle.entity);
257       return *this;
258     }
259
260 #else
261
262     //! Upcast to const reference to base type.
263     template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
264     operator const handle<T2>& () const
265     {
266       return reinterpret_cast<const handle<T2>&>(*this);
267     }
268
269     //! Upcast to non-const reference to base type.
270     //! NB: this cast can be dangerous, but required for legacy code; see #26377
271     template <class T2, typename = typename std::enable_if<is_base_but_not_same<T2, T>::value>::type>
272     operator handle<T2>& ()
273     {
274       return reinterpret_cast<handle<T2>&>(*this);
275     }
276
277 #endif /* OCCT_HANDLE_NOCAST */
278
279 #else /* fallback version for compilers not supporting default arguments of function templates (VC10, VC11, GCC below 4.3) */
280
281 #ifdef OCCT_HANDLE_NOCAST
282
283     //! Generalized copy constructor.
284     //! Constructs handle holding entity of base type (T) from the one which holds entity of derived type (T2).
285     template <class T2>
286     handle (const handle<T2>& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr) :
287       entity(theHandle.entity)
288     {
289       BeginScope();
290     }
291
292     //! Generalized move constructor
293     template <class T2>
294     handle (handle<T2>&& theHandle, typename std::enable_if <is_base_but_not_same <T, T2>::value>::type* = nullptr)
295       : entity(theHandle.entity)
296     {
297       theHandle.entity = 0;
298     }
299
300     //! Generalized assignment operator.
301     template <class T2>
302     handle operator = (const handle<T2>& theHandle)
303     {
304       std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
305       (void)aTypeCheckHelperVar;
306       Assign (theHandle.entity);
307       return *this;
308     }
309
310     //! Generalized move operator
311     template <class T2>
312     handle& operator= (handle<T2>&& theHandle)
313     {
314       std::enable_if <is_base_but_not_same <T, T2>::value, void*>::type aTypeCheckHelperVar;
315       (void)aTypeCheckHelperVar;
316       std::swap (this->entity, theHandle.entity);
317       return *this;
318     }
319
320 #else
321
322     //! Upcast to const reference to base type.
323     //! NB: this implementation will cause ambiguity errors on calls to overloaded
324     //! functions accepting handles to different types, since compatibility is 
325     //! checked in the cast code rather than ensured by SFINAE (possible with C++11)
326     template <class T2>
327     operator const handle<T2>& () const
328     {
329       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
330       // (handle is being cast to const& to handle of non-base type)
331       return reinterpret_cast<typename std::enable_if<is_base_but_not_same<T2, T>::value, const handle<T2>&>::type>(*this);
332     }
333
334     //! Upcast to non-const reference to base type.
335     //! NB: this cast can be dangerous, but required for legacy code; see #26377
336     template <class T2>
337     Standard_DEPRECATED("Passing non-const reference to handle of base type in function is unsafe; use variable of exact type")
338     operator handle<T2>& ()
339     {
340       // error "type is not a member of enable_if" will be generated if T2 is not sub-type of T
341       // (handle is being cast to const& to handle of non-base type)
342       return reinterpret_cast<typename std::enable_if<is_base_but_not_same<T2, T>::value, handle<T2>&>::type>(*this);
343     }
344
345 #endif /* OCCT_HANDLE_NOCAST */
346
347 #endif /* compiler switch */
348
349   private:
350
351     //! Assignment
352     void Assign (Standard_Transient *thePtr)
353     {
354       if (thePtr == entity)
355         return;
356       EndScope();
357       entity = thePtr;
358       BeginScope();
359     }
360   
361     //! Increment reference counter of referred object 
362     void BeginScope()
363     {
364       if (entity != 0)
365         entity->IncrementRefCounter();
366     }
367
368     //! Decrement reference counter and if 0, destroy referred object
369     void EndScope()
370     {
371       if (entity != 0 && entity->DecrementRefCounter() == 0)
372         entity->Delete();
373       entity = 0;
374     }
375
376     template <class T2> friend class handle;
377
378   private:
379     Standard_Transient* entity;
380   };
381
382 } // namespace opencascade
383
384 //! Define Handle() macro
385 #define Handle(Class) opencascade::handle<Class>
386
387 //! Global method HashCode(), for use in hash maps
388 template <class T>
389 inline Standard_Integer HashCode (const Handle(T)& theHandle, const Standard_Integer theUpper)
390 {
391   return ::HashCode (const_cast<Standard_Address>(static_cast<const void*>(theHandle.get())), theUpper);
392 }
393
394 //! For compatibility with previous versions of OCCT, defines typedef opencascade::handle<Class> Handle(Class)
395 #define DEFINE_STANDARD_HANDLECLASS(C1,C2,BC) class C1; typedef Handle(C1) Handle_##C1;
396 #define DEFINE_STANDARD_HANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Transient)
397 #define DEFINE_STANDARD_PHANDLE(C1,C2) DEFINE_STANDARD_HANDLECLASS(C1,C2,Standard_Persistent)
398
399 #endif