casacore
CountedPtr.h
Go to the documentation of this file.
1 //# CountedPtr.h: Referenced counted pointer classes
2 //# Copyright (C) 1993,1994,1995,1996,1999,2001
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef CASA_COUNTEDPTR_H
29 #define CASA_COUNTEDPTR_H
30 
31 #include <casacore/casa/aips.h>
32 
33 #if (defined(AIPS_CXX11) || (defined(__APPLE_CC__) && __APPLE_CC__ > 5621))
34 #include <memory>
35 #define SHARED_PTR std::shared_ptr
36 #define DYNAMIC_POINTER_CAST std::dynamic_pointer_cast
37 #define CONST_POINTER_CAST std::const_pointer_cast
38 #define STATIC_POINTER_CAST std::static_pointer_cast
39 #else
40 #include <tr1/memory>
41 #define SHARED_PTR std::tr1::shared_ptr
42 #define DYNAMIC_POINTER_CAST std::tr1::dynamic_pointer_cast
43 #define CONST_POINTER_CAST std::tr1::const_pointer_cast
44 #define STATIC_POINTER_CAST std::tr1::static_pointer_cast
45 #endif
46 
47 namespace casacore { //#Begin casa namespace
48 
49 
50 // <summary> act on dereference error </summary>
51 // <synopsis>
52 // Global function that throws an exception. It is called by the
53 // member functions of the counted pointer classes when an
54 // un-initialized (null) pointer is followed.
55 // </synopsis>
56 // <group name=dereference_error>
57 void throw_Null_CountedPtr_dereference_error();
58 // </group>
59 
60 
61 // <summary>Referenced counted pointer for constant data</summary>
62 // <use visibility=export>
63 // <reviewed reviewer="Friso Olnon" date="1995/03/15" tests="tCountedPtr" demos="">
64 
65 // <etymology>
66 // This class is <em>Counted</em> because it is reference counted.
67 // </etymology>
68 
69 // <synopsis>
70 // This class implements a reference counting mechanism. It
71 // allows <src>CountedPtr</src>s to be passed around freely,
72 // incrementing or decrementing the reference count as needed when one
73 // <src>CountedPtr</src> is assigned to another. When the
74 // reference count reaches zero the internal storage is deleted by
75 // default, but this behavior can be overridden.
76 //
77 // Internally the class uses std::shared_ptr to be thread-safe. Note that
78 // tr1 is used if the compiler does not support C++11 yet.
79 // </synopsis>
80 
81 // <motivation>
82 // Reference counting
83 // </motivation>
84 
85 template<class t>
87 {
88 
89 protected:
90  // Helper class to make deletion of object optional.
91  template <typename T>
92  class Deleter {
93  public:
94  Deleter (Bool deleteIt) : reallyDeleteIt_p (deleteIt) {}
95  void operator() (T * data) const { if (reallyDeleteIt_p) delete data;}
96  private:
98  };
99 
100 
101 public:
102 
103 
104 
105  // This constructor allows for the creation of a null
106  // <src>CountedPtr</src>. The assignment operator can be used
107  // to assign a null <src>CountedPtr</src> from another
108  // pointer.
109  //
111 
112  // This constructor sets up a reference count for the <src>val</src>
113  // pointer. By default, the data pointed to by <src>val</src>
114  // will be deleted when it is no longer referenced. Passing in
115  // <src>False</src> for <src>delit</src> will prevent the data
116  // from being deleted when the reference count reaches zero.
117  //
118  // <note role=warning> After the counted pointer is initialized
119  // the value should no longer be manipulated by the raw pointer of
120  // type <src>t*</src>.
121  // </note>
122  CountedPtr(t *val, Bool delit = True)
123  : pointerRep_p (val, Deleter<t> (delit))
124  {}
125 
126  // This copy constructor allows <src>CountedPtr</src>s to be
127  // initialized from other <src>CountedPtr</src>s for which the pointer TP*
128  // is convertible to T*.
129  template<typename TP>
131  : pointerRep_p(that.pointerRep_p)
132  {}
133 
134  // Create from a shared_ptr.
135  CountedPtr (const SHARED_PTR<t>& rep)
136  : pointerRep_p (rep)
137  {}
138 
139  // This destructor only deletes the really stored data when it was
140  // initialized as deletable and the reference count is zero.
142 
143  // This assignment operator allows <src>CountedPtr</src>s to be
144  // copied from other <src>CountedPtr</src>s for which the pointer TP*
145  // is convertible to t*.
146  template<typename TP>
148  {
149  pointerRep_p = that.pointerRep_p;
150  return *this;
151  }
152 
153  // Reset the pointer.
154  // <group>
155  void reset (t *val, Bool delit=True)
156  { pointerRep_p = PointerRep (val, Deleter<t>(delit)); }
157  void reset()
158  { pointerRep_p.reset(); }
159  // </group>
160 
161  // The <src>CountedPtr</src> indirection operator simply
162  // returns a reference to the value being protected. If the pointer
163  // is un-initialized (null), an exception will be thrown. The member
164  // function
165  // <linkto class="CountedPtr:null()const">null</linkto>()
166  // can be used to catch such a condition in time.
167  // <note role=tip> The address of the reference returned should
168  // not be stored for later use.
169  // </note>
170  t &operator*() const {
171  if (null()){
172  throw_Null_CountedPtr_dereference_error();
173  }
174  return pointerRep_p.operator* ();
175  }
176 
177  // This dereferencing operator behaves as expected; it returns the
178  // pointer to the value being protected, and then its dereferencing
179  // operator will be invoked as appropriate. If the pointer is
180  // un-initialized (null), an exception will be thrown. The member
181  // function
182  // <linkto class="CountedPtr:null()const">null</linkto>()
183  // can be used to catch such a condition in time.
184  t *operator->() const {
185  return get ();
186  }
187 
188  // Get the underlying pointer.
189  t* get () const {
190  return pointerRep_p.get();
191  }
192 
193  // Equality operator which checks to see if two
194  // <src>CountedPtr</src>s are pointing at the same thing.
195  Bool operator==(const CountedPtr<t> &other) const {
196  return (get() == other.get());
197  }
198  //# Note: use of const void* gives ambiguius overload error.
199  Bool operator==(int ptr) const {
200  return (ptr == 0 && get() == 0);
201  }
202 
203  // Non-equality operator which checks to see if two
204  // <src>CountedPtr</src>s are not pointing at the same thing.
205  Bool operator!=(const CountedPtr<t> &other) const {
206  return (get() != other.get() ? True : False);
207  }
208  //# Note: use of const void* gives ambiguius overload error.
209  Bool operator!=(int ptr) const {
210  return (ptr != 0 || get() != 0);
211  }
212 
213  // This assignment operator allows the object to which the current
214  // <src>CountedPtr</src> points to be changed.
215  CountedPtr<t> &
216  operator=(t *v)
217  {
218  pointerRep_p = PointerRep (v);
219  return * this;
220  }
221 
222  // Cast functions.
223  // <group>
224  template<typename U>
226  { return CountedPtr<U> (STATIC_POINTER_CAST<U> (pointerRep_p)); }
227  template<typename U>
229  { return CountedPtr<U> (CONST_POINTER_CAST<U> (pointerRep_p)); }
230  template<typename U>
232  { return CountedPtr<U> (DYNAMIC_POINTER_CAST<U> (pointerRep_p)); }
233  // </group>
234 
235  // Sometimes it is useful to know if there is more than one
236  // reference made. This is a way of getting that. Of course the point
237  // of these classes is that this information is normally not required.
238  uInt nrefs() const
239  { return pointerRep_p.use_count(); }
240 
241  // Check to see if this <src>CountedPtr</src> is
242  // un-initialized, null.
243  Bool null() const
244  { return get() == 0; }
245 
246  // Test if it contains a valid pointer.
247  operator bool() const
248  { return get() != 0; }
249 
250 private:
251  // Make all types of CountedPtr a friend for the templated operator=.
252  template<typename TP> friend class CountedPtr;
253 
254  typedef SHARED_PTR<t> PointerRep;
255 
256  PointerRep pointerRep_p;
257 };
258 
259 // A shared_ptr is used as implementation.
261  { return True; }
262 
263 // Cast the CountedPtr from one pointer type to another.
264 template<typename T, typename U>
266  { return that.template static_ptr_cast<T>(); }
267 template<typename T, typename U>
269  { return that.template const_ptr_cast<T>(); }
270 template<typename T, typename U>
272  { return that.template dynamic_ptr_cast<T>(); }
273 
274 
275 } //#End casa namespace
276 
277 
278 #ifndef CASACORE_NO_AUTO_TEMPLATES
279 #include <casacore/casa/Utilities/CountedPtr.tcc>
280 #endif //# CASACORE_NO_AUTO_TEMPLATES
281 
282 #endif
CountedPtr< t > & operator=(const CountedPtr< TP > &that)
This assignment operator allows CountedPtrs to be copied from other CountedPtrs for which the pointer...
Definition: CountedPtr.h:147
Bool operator==(const CountedPtr< t > &other) const
Equality operator which checks to see if two CountedPtrs are pointing at the same thing...
Definition: CountedPtr.h:195
CountedPtr(t *val, Bool delit=True)
This constructor sets up a reference count for the val pointer.
Definition: CountedPtr.h:122
CountedPtr(const SHARED_PTR< t > &rep)
Create from a shared_ptr.
Definition: CountedPtr.h:135
t * get() const
Get the underlying pointer.
Definition: CountedPtr.h:189
~CountedPtr()
This destructor only deletes the really stored data when it was initialized as deletable and the refe...
Definition: CountedPtr.h:141
Bool null() const
Check to see if this CountedPtr is un-initialized, null.
Definition: CountedPtr.h:243
Helper class to make deletion of object optional.
Definition: CountedPtr.h:92
CountedPtr(const CountedPtr< TP > &that)
This copy constructor allows CountedPtrs to be initialized from other CountedPtrs for which the point...
Definition: CountedPtr.h:130
CountedPtr< t > & operator=(t *v)
This assignment operator allows the object to which the current CountedPtr points to be changed...
Definition: CountedPtr.h:216
SHARED_PTR< t > PointerRep
Definition: CountedPtr.h:254
t & operator*() const
The CountedPtr indirection operator simply returns a reference to the value being protected...
Definition: CountedPtr.h:170
Bool operator!=(int ptr) const
Definition: CountedPtr.h:209
void reset(t *val, Bool delit=True)
Reset the pointer.
Definition: CountedPtr.h:155
CountedPtr< U > dynamic_ptr_cast() const
Definition: CountedPtr.h:231
Referenced counted pointer for constant data.
Definition: CountedPtr.h:86
uInt nrefs() const
Sometimes it is useful to know if there is more than one reference made.
Definition: CountedPtr.h:238
PointerRep pointerRep_p
Definition: CountedPtr.h:256
Bool operator==(int ptr) const
Definition: CountedPtr.h:199
CountedPtr< U > const_ptr_cast() const
Definition: CountedPtr.h:228
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
Bool operator!=(const CountedPtr< t > &other) const
Non-equality operator which checks to see if two CountedPtrs are not pointing at the same thing...
Definition: CountedPtr.h:205
CountedPtr< T > static_pointer_cast(const CountedPtr< U > &that)
Cast the CountedPtr from one pointer type to another.
Definition: CountedPtr.h:265
CountedPtr< T > const_pointer_cast(const CountedPtr< U > &that)
Definition: CountedPtr.h:268
const Bool False
Definition: aipstype.h:41
CountedPtr()
This constructor allows for the creation of a null CountedPtr.
Definition: CountedPtr.h:110
CountedPtr< U > static_ptr_cast() const
Cast functions.
Definition: CountedPtr.h:225
void operator()(T *data) const
Definition: CountedPtr.h:95
t * operator->() const
This dereferencing operator behaves as expected; it returns the pointer to the value being protected...
Definition: CountedPtr.h:184
const Bool True
Definition: aipstype.h:40
CountedPtr< T > dynamic_pointer_cast(const CountedPtr< U > &that)
Definition: CountedPtr.h:271
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:48
Bool countedPtrShared()
A shared_ptr is used as implementation.
Definition: CountedPtr.h:260