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 #include <memory>
33 
34 //# Define the old names for backward compatibility.
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 
40 
41 namespace casacore { //#Begin casa namespace
42 
43 
44 // <summary> act on dereference error </summary>
45 // <synopsis>
46 // Global function that throws an exception. It is called by the
47 // member functions of the counted pointer classes when an
48 // un-initialized (null) pointer is followed.
49 // </synopsis>
50 // <group name=dereference_error>
51 void throw_Null_CountedPtr_dereference_error();
52 // </group>
53 
54 
55 // <summary>Referenced counted pointer for constant data</summary>
56 // <use visibility=export>
57 // <reviewed reviewer="Friso Olnon" date="1995/03/15" tests="tCountedPtr" demos="">
58 
59 // <etymology>
60 // This class is <em>Counted</em> because it is reference counted.
61 // </etymology>
62 
63 // <synopsis>
64 // This class implements a reference counting mechanism. It
65 // allows <src>CountedPtr</src>s to be passed around freely,
66 // incrementing or decrementing the reference count as needed when one
67 // <src>CountedPtr</src> is assigned to another. When the
68 // reference count reaches zero the internal storage is deleted by
69 // default, but this behavior can be overridden.
70 //
71 // Internally the class uses std::shared_ptr to be thread-safe. Note that
72 // tr1 is used if the compiler does not support C++11 yet.
73 // </synopsis>
74 
75 // <motivation>
76 // Reference counting
77 // </motivation>
78 
79 template<class t>
81 {
82 
83 protected:
84  // Helper class to make deletion of object optional.
85  template <typename T>
86  class Deleter {
87  public:
88  Deleter (Bool deleteIt) : reallyDeleteIt_p (deleteIt) {}
89  void operator() (T * data) const { if (reallyDeleteIt_p) delete data;}
90  private:
92  };
93 
94 
95 public:
96 
97 
98 
99  // This constructor allows for the creation of a null
100  // <src>CountedPtr</src>. The assignment operator can be used
101  // to assign a null <src>CountedPtr</src> from another
102  // pointer.
103  //
105 
106  // This constructor sets up a reference count for the <src>val</src>
107  // pointer. By default, the data pointed to by <src>val</src>
108  // will be deleted when it is no longer referenced. Passing in
109  // <src>False</src> for <src>delit</src> will prevent the data
110  // from being deleted when the reference count reaches zero.
111  //
112  // <note role=warning> After the counted pointer is initialized
113  // the value should no longer be manipulated by the raw pointer of
114  // type <src>t*</src>.
115  // </note>
116  CountedPtr(t *val, Bool delit = True)
117  : pointerRep_p (val, Deleter<t> (delit))
118  {}
119 
120  // This copy constructor allows <src>CountedPtr</src>s to be
121  // initialized from other <src>CountedPtr</src>s for which the pointer TP*
122  // is convertible to T*.
123  template<typename TP>
125  : pointerRep_p(that.pointerRep_p)
126  {}
127 
128  // Create from a shared_ptr.
129  CountedPtr (const std::shared_ptr<t>& rep)
130  : pointerRep_p (rep)
131  {}
132 
133  // This destructor only deletes the really stored data when it was
134  // initialized as deletable and the reference count is zero.
136 
137  // This assignment operator allows <src>CountedPtr</src>s to be
138  // copied from other <src>CountedPtr</src>s for which the pointer TP*
139  // is convertible to t*.
140  template<typename TP>
142  {
143  pointerRep_p = that.pointerRep_p;
144  return *this;
145  }
146 
147  // Reset the pointer.
148  // <group>
149  void reset (t *val, Bool delit=True)
150  { pointerRep_p = PointerRep (val, Deleter<t>(delit)); }
151  void reset()
152  { pointerRep_p.reset(); }
153  // </group>
154 
155  // The <src>CountedPtr</src> indirection operator simply
156  // returns a reference to the value being protected. If the pointer
157  // is un-initialized (null), an exception will be thrown. The member
158  // function
159  // <linkto class="CountedPtr:null()const">null</linkto>()
160  // can be used to catch such a condition in time.
161  // <note role=tip> The address of the reference returned should
162  // not be stored for later use.
163  // </note>
164  t &operator*() const {
165  if (null()){
166  throw_Null_CountedPtr_dereference_error();
167  }
168  return pointerRep_p.operator* ();
169  }
170 
171  // This dereferencing operator behaves as expected; it returns the
172  // pointer to the value being protected, and then its dereferencing
173  // operator will be invoked as appropriate. If the pointer is
174  // un-initialized (null), an exception will be thrown. The member
175  // function
176  // <linkto class="CountedPtr:null()const">null</linkto>()
177  // can be used to catch such a condition in time.
178  t *operator->() const {
179  return get ();
180  }
181 
182  // Get the underlying pointer.
183  t* get () const {
184  return pointerRep_p.get();
185  }
186 
187  // Equality operator which checks to see if two
188  // <src>CountedPtr</src>s are pointing at the same thing.
189  Bool operator==(const CountedPtr<t> &other) const {
190  return (get() == other.get());
191  }
192  //# Note: use of const void* gives ambiguius overload error.
193  Bool operator==(int ptr) const {
194  return (ptr == 0 && get() == 0);
195  }
196 
197  // Non-equality operator which checks to see if two
198  // <src>CountedPtr</src>s are not pointing at the same thing.
199  Bool operator!=(const CountedPtr<t> &other) const {
200  return (get() != other.get() ? True : False);
201  }
202  //# Note: use of const void* gives ambiguius overload error.
203  Bool operator!=(int ptr) const {
204  return (ptr != 0 || get() != 0);
205  }
206 
207  // This assignment operator allows the object to which the current
208  // <src>CountedPtr</src> points to be changed.
209  CountedPtr<t> &
210  operator=(t *v)
211  {
212  pointerRep_p = PointerRep (v);
213  return * this;
214  }
215 
216  // Cast functions.
217  // <group>
218  template<typename U>
220  { return CountedPtr<U> (std::static_pointer_cast<U> (pointerRep_p)); }
221  template<typename U>
223  { return CountedPtr<U> (std::const_pointer_cast<U> (pointerRep_p)); }
224  template<typename U>
226  { return CountedPtr<U> (std::dynamic_pointer_cast<U> (pointerRep_p)); }
227  // </group>
228 
229  // Sometimes it is useful to know if there is more than one
230  // reference made. This is a way of getting that. Of course the point
231  // of these classes is that this information is normally not required.
232  uInt nrefs() const
233  { return pointerRep_p.use_count(); }
234 
235  // Check to see if this <src>CountedPtr</src> is
236  // un-initialized, null.
237  Bool null() const
238  { return get() == 0; }
239 
240  // Test if it contains a valid pointer.
241  operator bool() const
242  { return get() != 0; }
243 
244 private:
245  // Make all types of CountedPtr a friend for the templated operator=.
246  template<typename TP> friend class CountedPtr;
247 
248  typedef std::shared_ptr<t> PointerRep;
249 
251 };
252 
253 // A shared_ptr is used as implementation.
255  { return True; }
256 
257 // Cast the CountedPtr from one pointer type to another.
258 template<typename T, typename U>
260  { return that.template static_ptr_cast<T>(); }
261 template<typename T, typename U>
263  { return that.template const_ptr_cast<T>(); }
264 template<typename T, typename U>
266  { return that.template dynamic_ptr_cast<T>(); }
267 
268 
269 } //#End casa namespace
270 
271 
272 #ifndef CASACORE_NO_AUTO_TEMPLATES
273 #include <casacore/casa/Utilities/CountedPtr.tcc>
274 #endif //# CASACORE_NO_AUTO_TEMPLATES
275 
276 #endif
Helper class to make deletion of object optional.
Definition: CountedPtr.h:86
void operator()(T *data) const
Definition: CountedPtr.h:89
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
std::shared_ptr< t > PointerRep
Definition: CountedPtr.h:248
t & operator*() const
The CountedPtr indirection operator simply returns a reference to the value being protected.
Definition: CountedPtr.h:164
PointerRep pointerRep_p
Definition: CountedPtr.h:250
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:189
~CountedPtr()
This destructor only deletes the really stored data when it was initialized as deletable and the refe...
Definition: CountedPtr.h:135
CountedPtr< t > & operator=(t *v)
This assignment operator allows the object to which the current CountedPtr points to be changed.
Definition: CountedPtr.h:210
CountedPtr< U > dynamic_ptr_cast() const
Definition: CountedPtr.h:225
CountedPtr< U > static_ptr_cast() const
Cast functions.
Definition: CountedPtr.h:219
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:141
CountedPtr(const std::shared_ptr< t > &rep)
Create from a shared_ptr.
Definition: CountedPtr.h:129
t * operator->() const
This dereferencing operator behaves as expected; it returns the pointer to the value being protected,...
Definition: CountedPtr.h:178
void reset(t *val, Bool delit=True)
Reset the pointer.
Definition: CountedPtr.h:149
t * get() const
Get the underlying pointer.
Definition: CountedPtr.h:183
Bool operator!=(int ptr) const
Definition: CountedPtr.h:203
Bool operator==(int ptr) const
Definition: CountedPtr.h:193
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:199
CountedPtr< U > const_ptr_cast() const
Definition: CountedPtr.h:222
CountedPtr(const CountedPtr< TP > &that)
This copy constructor allows CountedPtrs to be initialized from other CountedPtrs for which the point...
Definition: CountedPtr.h:124
CountedPtr(t *val, Bool delit=True)
This constructor sets up a reference count for the val pointer.
Definition: CountedPtr.h:116
CountedPtr()
This constructor allows for the creation of a null CountedPtr.
Definition: CountedPtr.h:104
uInt nrefs() const
Sometimes it is useful to know if there is more than one reference made.
Definition: CountedPtr.h:232
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
CountedPtr< T > const_pointer_cast(const CountedPtr< U > &that)
Definition: CountedPtr.h:262
CountedPtr< T > static_pointer_cast(const CountedPtr< U > &that)
Cast the CountedPtr from one pointer type to another.
Definition: CountedPtr.h:259
Bool countedPtrShared()
A shared_ptr is used as implementation.
Definition: CountedPtr.h:254
CountedPtr< T > dynamic_pointer_cast(const CountedPtr< U > &that)
Definition: CountedPtr.h:265
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43