0024023: Revamp the OCCT Handle -- handle
[occt.git] / src / Standard / Handle_Standard_Transient.hxx
1 // Copyright (c) 1998-1999 Matra Datavision
2 // Copyright (c) 1999-2014 OPEN CASCADE SAS
3 //
4 // This file is part of Open CASCADE Technology software library.
5 //
6 // This library is free software; you can redistribute it and/or modify it under
7 // the terms of the GNU Lesser General Public License version 2.1 as published
8 // by the Free Software Foundation, with special exception defined in the file
9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
10 // distribution for complete text of the license and disclaimer of any warranty.
11 //
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
14
15 #ifndef _Handle_Standard_Transient_HeaderFile
16 #define _Handle_Standard_Transient_HeaderFile
17
18 #include <Standard.hxx>
19 #include <Standard_DefineAlloc.hxx>
20 #include <Standard_PrimitiveTypes.hxx>
21 #include <Standard_Transient_proto.hxx>
22
23 #ifdef _WIN32
24 // Disable the warning "conversion from 'unsigned int' to Standard_Transient *"
25 #pragma warning (push)
26 #pragma warning (disable:4312)
27 #endif
28
29 class Handle_Standard_Transient;
30
31 Standard_EXPORT Standard_Integer HashCode(const Handle(Standard_Transient)& ,const Standard_Integer);
32
33 /** 
34  * Base class for hierarchy of smart pointers (Handles) for Transient
35  * objects. Uses reference counting technique to control life time
36  * of the referred object.
37  *
38  * Note that Handle should never be initialized by pointer to object
39  * created in the stack; only dinamically allocated pointers shall be used. 
40  */
41      
42 class Handle(Standard_Transient)
43 {
44 public:
45   
46   // Public methods
47   
48   //! Empty constructor
49   Handle(Standard_Transient) () 
50     : entity(0) 
51   {
52   }
53
54   //! Constructor from pointer to new object
55   Handle(Standard_Transient) (const Standard_Transient *anItem)
56     : entity ( (Standard_Transient*)anItem )
57   {
58     BeginScope();
59   }
60
61   //! Copy constructor
62   Handle(Standard_Transient) (const Handle(Standard_Transient)& aTid) 
63     : entity ( aTid.entity )
64   {
65     BeginScope();
66   } 
67
68   //! Destructor
69   ~Handle(Standard_Transient)()
70   {
71     EndScope();
72   }
73
74   //! Assignment operator
75   Handle(Standard_Transient)& operator=(const Handle(Standard_Transient)& aHandle)
76   {
77     Assign(aHandle.Access());
78     return *this;
79   }
80
81   //! Assignment operator
82   Handle(Standard_Transient)& operator=(const Standard_Transient* anItem)
83   {
84     Assign(anItem);
85     return *this;
86   }
87
88   //! Nullify the handle
89   void Nullify()
90   {
91     EndScope();
92   }
93
94   //! Check for being null
95   Standard_Boolean IsNull() const
96   {
97     return entity == 0;
98   } 
99
100   //! Returns pointer to referred object
101   Standard_Transient* Access()
102   {
103     return entity;
104   } 
105   
106   //! Returns const pointer to referred object
107   const Standard_Transient* Access() const
108   {
109     return entity;
110   } 
111
112   //! Cast to pointer to referred object
113   operator Standard_Transient*()
114   {
115     return entity;
116   }
117
118   //! Cast to const pointer to referred object
119   operator const Standard_Transient*() const
120   {
121     return entity;
122   }
123
124   //! Member access operator (note non-const)
125   Standard_Transient* operator->() const
126   {
127     return entity;
128   }
129
130   //! STL-style member accessor
131   Standard_Transient* get() const
132   {
133     return entity;
134   }
135
136   //! Dereferencing operator
137   Standard_Transient& operator*()
138   {
139     return *entity;
140   }
141
142   //! Const dereferencing operator
143   const Standard_Transient& operator*() const
144   {
145     return *entity;
146   }
147
148   //! Check for equality
149   int operator==(const Handle(Standard_Transient)& right) const
150   {
151     return entity == right.entity;
152   }
153
154   //! Check for equality
155   int operator==(const Standard_Transient *right) const
156   {
157     return entity == right;
158   }
159
160   //! Check for equality
161   friend bool operator==(const Standard_Transient *left, const Handle(Standard_Transient)& right)
162   {
163     return left == right.entity;
164   }
165
166   //! Check for inequality
167   bool operator!=(const Handle(Standard_Transient)& right) const
168   {
169     return entity != right.entity;
170   }
171
172   //! Check for inequality
173   bool operator!=(const Standard_Transient *right) const
174   {
175     return entity != right;
176   }
177
178   //! Check for inequality
179   friend bool operator!=(const Standard_Transient *left, const Handle(Standard_Transient)& right)
180   {
181     return left != right.entity;
182   }
183
184   //! Down casting operator; dummy provided for consistency with other classes
185   //! (descendants)
186   static const Handle(Standard_Transient)& DownCast(const Handle(Standard_Transient)& AnObject)
187   { 
188     return AnObject;
189   }
190
191   //! Dump pointer to a referred object to a stream
192   Standard_EXPORT void Dump(Standard_OStream& out) const;
193
194 protected:
195   // Protected methods for descendants
196
197   //! Returns non-const pointer to referred object
198   Standard_Transient* ControlAccess() const
199   {
200     return entity;
201   } 
202
203   //! Assignment
204   Standard_EXPORT void Assign (const Standard_Transient *anItem);
205   
206 private:
207   // Private methods
208
209   //! Increment reference counter of referred object 
210   Standard_EXPORT void BeginScope();
211
212   //! Decrement reference counter and if 0, destroy referred object
213   Standard_EXPORT void EndScope();
214
215 public:
216
217   DEFINE_STANDARD_ALLOC
218
219 private:
220   // Field
221   Standard_Transient *entity;
222 };
223
224 //! Function in global scope to check handles for equality.
225 //! Will be used with standard OCCT collections like NCollection_DataMap within NCollection_DefaultHasher
226 //! when there are no specialization defined for concrete type.
227 //! Notice that this implementation compares only pointers to objects!
228 inline Standard_Boolean IsEqual (const Handle(Standard_Transient)& theFirst,
229                                  const Handle(Standard_Transient)& theSecond)
230 {
231   return theFirst == theSecond;
232 }
233
234 #ifdef _WIN32
235 #pragma warning (pop)
236 #endif
237
238 #endif