refPtr.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | www.openfoam.com
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8  Copyright (C) 2016 OpenFOAM Foundation
9  Copyright (C) 2018-2021 OpenCFD Ltd.
10 -------------------------------------------------------------------------------
11 License
12  This file is part of OpenFOAM.
13 
14  OpenFOAM is free software: you can redistribute it and/or modify it
15  under the terms of the GNU General Public License as published by
16  the Free Software Foundation, either version 3 of the License, or
17  (at your option) any later version.
18 
19  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
20  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
21  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22  for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
26 
27 Class
28  Foam::refPtr
29 
30 Description
31  A class for managing references or pointers (no reference counting)
32 
33 SourceFiles
34  refPtrI.H
35 
36 See also
37  Foam::autoPtr
38  Foam::tmp
39 
40 \*---------------------------------------------------------------------------*/
41 
42 #ifndef refPtr_H
43 #define refPtr_H
44 
45 #include "autoPtr.H"
46 #include "tmp.H"
47 
48 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
49 
50 namespace Foam
51 {
52 
53 /*---------------------------------------------------------------------------*\
54  Class refPtr Declaration
55 \*---------------------------------------------------------------------------*/
56 
57 template<class T>
58 class refPtr
59 {
60  // Private Data
61 
62  //- The stored reference type
63  enum refType
64  {
65  PTR,
66  CREF,
67  REF
68  };
69 
70  //- The managed pointer or address of the object (reference)
71  mutable T* ptr_;
72 
73  //- The type (managed pointer | object reference)
74  mutable refType type_;
75 
76 
77 public:
78 
79  // STL type definitions
80 
81  //- Type of object being managed or referenced
82  typedef T element_type;
83 
84  //- Pointer to type of object being managed or referenced
85  typedef T* pointer;
86 
87 
88  //- Null reference counter class
90 
91 
92  // Factory Methods
93 
94  //- Construct refPtr of T with forwarding arguments
95  // \param args list of arguments with which an instance of T
96  // will be constructed.
97  //
98  // \note Similar to std::make_shared, but the overload for
99  // array types is not disabled.
100  template<class... Args>
101  inline static refPtr<T> New(Args&&... args);
102 
103  //- Construct refPtr from derived type with forwarding arguments
104  // \param args list of arguments with which an instance of U
105  // will be constructed.
106  //
107  // \note Similar to New but for derived types
108  template<class U, class... Args>
109  inline static refPtr<T> NewFrom(Args&&... args);
110 
111 
112  // Constructors
113 
114  //- Construct with no managed pointer.
115  inline constexpr refPtr() noexcept;
116 
117  //- Construct with no managed pointer (literal nullptr).
118  inline constexpr refPtr(std::nullptr_t) noexcept;
119 
120  //- Construct, taking ownership of the pointer.
121  inline explicit constexpr refPtr(T* p) noexcept;
122 
123  //- Move construct from autoPtr, transferring ownership.
124  inline explicit refPtr(autoPtr<T>&& ptr) noexcept;
125 
126  //- Move construct from unique_ptr, transferring ownership.
127  inline explicit refPtr(std::unique_ptr<T>&& ptr) noexcept;
128 
129  //- Construct for a const reference to an object.
130  inline constexpr refPtr(const T& obj) noexcept;
131 
132  //- Move construct, transferring ownership.
133  inline refPtr(refPtr<T>&& rhs) noexcept;
134 
135  //- Copy construct (shallow copy)
136  inline refPtr(const refPtr<T>& rhs);
137 
138  //- Copy/move construct. Optionally reusing pointer.
139  inline refPtr(const refPtr<T>& rhs, bool reuse);
140 
141 
142  //- Destructor: deletes managed pointer
143  inline ~refPtr();
144 
145 
146  // Member Functions
147 
148  //- The type-name, constructed from type-name of T
149  inline static word typeName();
150 
151 
152  // Query
153 
154  //- True if pointer/reference is non-null.
155  bool good() const noexcept { return bool(ptr_); }
156 
157  //- If the stored/referenced content is const
158  bool is_const() const noexcept { return type_ == CREF; }
159 
160  //- True if this is a managed pointer (not a reference)
161  bool is_pointer() const noexcept { return type_ == PTR; }
162 
163  //- True if this is a non-null managed pointer
164  inline bool movable() const noexcept;
165 
166 
167  // Access
168 
169  //- Return pointer without nullptr checking.
170  T* get() noexcept { return ptr_; }
171 
172  //- Return const pointer without nullptr checking.
173  const T* get() const noexcept { return ptr_; }
174 
175  //- Return const reference to the object or to the contents
176  //- of a (non-null) managed pointer.
177  // Fatal for a null managed pointer
178  inline const T& cref() const;
179 
180  //- Return non-const reference to the contents of a non-null
181  //- managed pointer.
182  // Fatal for a null managed pointer or if the object is const.
183  inline T& ref() const;
184 
185  //- Return non-const reference to the object or to the contents
186  //- of a (non-null) managed pointer, with an additional const_cast.
187  // Fatal for a null managed pointer.
188  inline T& constCast() const;
189 
190  //- Return a shallow copy as a wrapped reference, preserving the
191  //- const/non-const status.
192  inline refPtr<T> shallowClone() const noexcept;
193 
194 
195  // Edit
196 
197  //- Release ownership and return the pointer.
198  //- A no-op for reference objects (returns nullptr).
199  // \remark Method naming consistent with std::unique_ptr
200  inline T* release() noexcept;
201 
202  //- Return managed pointer for reuse, or clone() the object reference.
203  // \remark Method naming consistent with Foam::tmp
204  inline T* ptr() const;
205 
206  //- If object pointer points to valid object:
207  //- delete object and set pointer to nullptr
208  inline void clear() const noexcept;
209 
210 
211  //- Clear existing and transfer ownership.
212  inline void reset(refPtr<T>&& other) noexcept;
213 
214  //- Delete managed pointer and set to new given pointer
215  inline void reset(T* p = nullptr) noexcept;
216 
217  //- Clear existing and transfer ownership from autoPtr.
218  void reset(autoPtr<T>&& other) noexcept { reset(other.release()); }
219 
220  //- Clear existing and transfer ownership from unique_ptr
221  void reset(std::unique_ptr<T>&& other) { reset(other.release()); }
222 
223 
224  //- Clear existing and set (const) reference from other
225  inline void cref(const refPtr<T>& other) noexcept;
226 
227  //- Clear existing and set (const) reference
228  inline void cref(const T& obj) noexcept;
229 
230  //- Clear existing and set (const) reference to pointer content.
231  // The pointer can be null, which is handled like a clear().
232  inline void cref(const T* p) noexcept;
233 
234 
235  //- Clear existing and set (non-const) reference
236  inline void ref(T& obj) noexcept;
237 
238  //- Clear existing and set (non-const) reference to pointer content.
239  // The pointer can be null, which is handled like a clear().
240  inline void ref(T* p) noexcept;
241 
242 
243  //- Swaps the managed object with other.
244  inline void swap(refPtr<T>& other) noexcept;
245 
246 
247  // Member Operators
248 
249  //- Return const reference to the object.
250  // Fatal if nothing is managed
251  inline const T& operator*() const;
252 
253  //- Return reference to the managed object.
254  // Fatal if nothing is managed or if the object is const.
255  inline T& operator*();
256 
257  //- Dereferences (const) pointer to the managed object.
258  // Fatal if nothing is managed.
259  inline const T* operator->() const;
260 
261  //- Dereferences (non-const) pointer to the managed object.
262  // Fatal if nothing is managed or if the object is const.
263  inline T* operator->();
264 
265  //- Return const reference to the object - same as cref() method.
266  const T& operator()() const { return cref(); }
267 
268 
269  // Casting
270 
271  //- True if pointer/reference is non-null. Same as good()
272  explicit operator bool() const noexcept { return bool(ptr_); }
273 
274  //- Cast to underlying data type, using the cref() method.
275  operator const T&() const { return cref(); }
276 
277 
278  // Assignment
279 
280  //- Transfer ownership of the managed pointer.
281  // Fatal for a null managed pointer or if the object is const.
282  inline void operator=(const refPtr<T>& other);
283 
284  //- Clear existing and transfer ownership.
285  inline void operator=(refPtr<T>&& other) noexcept;
286 
287  //- Take ownership of the pointer.
288  // Fatal for a null pointer
289  inline void operator=(T* p);
290 
291  //- Reset via assignment from literal nullptr
292  inline void operator=(std::nullptr_t) noexcept;
293 
294  //- Conversion to tmp, releases pointer or shallow-copies reference
295  inline operator tmp<T>();
296 
297 
298  // Housekeeping
299 
300  //- Identical to good(), or bool operator
301  bool valid() const noexcept { return bool(ptr_); }
302 
303  //- Deprecated(2020-07) True if a null managed pointer
304  //
305  // \deprecated(2020-07) - use bool operator
306  FOAM_DEPRECATED_FOR(2020-07, "bool operator")
307  bool empty() const noexcept { return !ptr_; }
308 };
309 
310 
311 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
312 
313 // Global Functions
314 
315 //- Specialized Swap algorithm for refPtr.
316 // Swaps the pointers and types of lhs and rhs. Calls \c lhs.swap(rhs)
317 template<class T>
318 void Swap(refPtr<T>& lhs, refPtr<T>& rhs)
319 {
320  lhs.swap(rhs);
321 }
322 
323 
324 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
325 
326 } // End namespace Foam
327 
328 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
329 
330 #include "refPtrI.H"
331 
332 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
333 
334 #endif
335 
336 // ************************************************************************* //
Foam::refPtr::New
static refPtr< T > New(Args &&... args)
Construct refPtr of T with forwarding arguments.
Foam::refPtr::release
T * release() noexcept
Definition: refPtrI.H:246
p
volScalarField & p
Definition: createFieldRefs.H:8
Foam::refPtr::swap
void swap(refPtr< T > &other) noexcept
Swaps the managed object with other.
Definition: refPtrI.H:370
Foam::Swap
void Swap(DynamicList< T, SizeMinA > &a, DynamicList< T, SizeMinB > &b)
Definition: DynamicList.H:429
Foam::word
A class for handling words, derived from Foam::string.
Definition: word.H:65
Foam::tmp
A class for managing temporary objects.
Definition: PtrList.H:61
Foam::refPtr::is_pointer
bool is_pointer() const noexcept
True if this is a managed pointer (not a reference)
Definition: refPtr.H:160
Foam::refPtr::shallowClone
refPtr< T > shallowClone() const noexcept
Definition: refPtrI.H:231
Foam::refPtr::reset
void reset(std::unique_ptr< T > &&other)
Clear existing and transfer ownership from unique_ptr.
Definition: refPtr.H:220
Foam::refPtr::get
T * get() noexcept
Return pointer without nullptr checking.
Definition: refPtr.H:169
Foam::refPtr::element_type
T element_type
Type of object being managed or referenced.
Definition: refPtr.H:81
Foam::refPtr::get
const T * get() const noexcept
Return const pointer without nullptr checking.
Definition: refPtr.H:172
Foam::refPtr::valid
bool valid() const noexcept
Identical to good(), or bool operator.
Definition: refPtr.H:300
Foam::refPtr::clear
void clear() const noexcept
Definition: refPtrI.H:283
Foam::refPtr::reset
void reset(refPtr< T > &&other) noexcept
Clear existing and transfer ownership.
Definition: refPtrI.H:303
Foam::refPtr::cref
const T & cref() const
Definition: refPtrI.H:189
Foam::refPtr::constCast
T & constCast() const
Definition: refPtrI.H:224
Foam::refPtr::reset
void reset(autoPtr< T > &&other) noexcept
Clear existing and transfer ownership from autoPtr.
Definition: refPtr.H:217
Foam::T
void T(FieldField< Field, Type > &f1, const FieldField< Field, Type > &f2)
Definition: FieldFieldFunctions.C:58
Foam::refPtr::movable
bool movable() const noexcept
True if this is a non-null managed pointer.
Definition: refPtrI.H:182
Foam
Namespace for OpenFOAM.
Definition: atmBoundaryLayer.C:33
refPtrI.H
Foam::refPtr::operator*
const T & operator*() const
Return const reference to the object.
Definition: refPtrI.H:387
Foam::refPtr::refCount
Foam::refCount::zero refCount
Null reference counter class.
Definition: refPtr.H:88
Foam::refPtr::ptr
T * ptr() const
Return managed pointer for reuse, or clone() the object reference.
Definition: refPtrI.H:260
Foam::autoPtr
Pointer management similar to std::unique_ptr, with some additional methods and type checking.
Definition: HashPtrTable.H:53
U
U
Definition: pEqn.H:72
Foam::refCount::zero
A non-counting (dummy) refCount.
Definition: refCount.H:59
tmp.H
Foam::refPtr::operator()
const T & operator()() const
Return const reference to the object - same as cref() method.
Definition: refPtr.H:265
Foam::refPtr::empty
bool empty() const noexcept
Deprecated(2020-07) True if a null managed pointer.
Definition: refPtr.H:306
Foam::refPtr::refPtr
constexpr refPtr() noexcept
Construct with no managed pointer.
Definition: refPtrI.H:60
bool
bool
Definition: EEqn.H:20
Foam::FOAM_DEPRECATED_FOR
class FOAM_DEPRECATED_FOR(2017-05, "Foam::Enum") NamedEnum
Definition: NamedEnum.H:69
Foam::refPtr::NewFrom
static refPtr< T > NewFrom(Args &&... args)
Construct refPtr from derived type with forwarding arguments.
Foam::refPtr::pointer
T * pointer
Pointer to type of object being managed or referenced.
Definition: refPtr.H:84
Foam::refPtr::good
bool good() const noexcept
True if pointer/reference is non-null.
Definition: refPtr.H:154
Foam::refPtr::operator=
void operator=(const refPtr< T > &other)
Transfer ownership of the managed pointer.
Definition: refPtrI.H:456
Foam::refPtr::ref
T & ref() const
Definition: refPtrI.H:203
args
Foam::argList args(argc, argv)
Foam::refPtr::operator->
const T * operator->() const
Dereferences (const) pointer to the managed object.
Definition: refPtrI.H:421
Foam::refPtr::typeName
static word typeName()
The type-name, constructed from type-name of T.
Definition: refPtrI.H:51
Foam::refPtr
A class for managing references or pointers (no reference counting)
Definition: PtrList.H:60
Foam::refPtr::is_const
bool is_const() const noexcept
If the stored/referenced content is const.
Definition: refPtr.H:157
autoPtr.H