rcolyer.net
RC Lib  Version 202403231100
RevPtr.h
Go to the documentation of this file.
1 /////////////////////////////////////////////////////////////////////
2 //
3 // RC Library, (c) 2011-2014, Ryan A. Colyer
4 // Distributed under the Boost Software License, v1.0. (LICENSE.txt)
5 //
6 /// \file RevPtr.h
7 /// A reference counting pointer that revokes (NULLs) all copies when
8 /// one set to AutoRevoke(true) leaves scope.
9 /////////////////////////////////////////////////////////////////////
10 
11 #ifndef RC_REVPTR_H
12 #define RC_REVPTR_H
13 
14 
15 #include "Types.h"
16 #include "Errors.h"
17 #include "Macros.h"
18 #include <iostream>
19 
20 #ifdef CPP11
21 #include <atomic>
22 #endif
23 
24 
25 namespace RC {
26  /// @cond EXTERNAL
27  template <class T> class Ptr;
28  template <class T> class APtr;
29  /// @endcond
30 
31  /// A reference counting pointer that revokes (NULLs) all copies when
32  /// one set to AutoRevoke(true) leaves scope.
33  /** This pointer class does not automatically delete the object pointed to,
34  * so that it can be used for self-referential purposes. For automatic
35  * deletion, use an APtr, and create a RevPtr family that refers to the
36  * Ptr of the same scope. Like Ptr and APtr, dereferencing a null
37  * RevPtr throws ErrorMsgNull.
38  * Note: Revocation is thread safe, but a previously extracted raw ptr
39  * could remain in use after revocation. Be mindful of this in threading
40  * architecture design.
41  * @see Ptr
42  * @see APtr
43  */
44  template <class T>
45  class RevPtr {
46  public:
47 
48  /// Default constructor assigning the value of the pointer.
49  /** @param t_ptr The new pointer value.
50  */
51  RevPtr(T* t_ptr = NULL) {
52  helper = new PtrHelper(t_ptr, false);
53  auto_revoke = false;
54  }
55 
56  /// Copy constructor.
57  /** @param other The RevPtr to copy.
58  */
59  inline RevPtr(const RevPtr<T>& other) {
60  other.helper->Add();
61  helper = other.helper;
62  auto_revoke = false;
63  }
64 
65  /// A conversion constructor which creates a new RevPtr from a Ptr of the
66  /// same or a derived type.
67  /** @param other The Ptr from which the pointer should be used to make
68  * this RevPtr
69  */
70  inline RevPtr(const Ptr<T>& other) {
71  helper = new PtrHelper(other, false);
72  auto_revoke = false;
73  }
74 
75  /// A conversion constructor which creates a new RevPtr from an APtr of
76  /// the same or a derived type.
77  /** @param other The APtr from which the pointer should be used to make
78  * this RevPtr
79  */
80  inline RevPtr(const APtr<T>& other) {
81  helper = new PtrHelper(other, false);
82  auto_revoke = false;
83  }
84 
85 
86  /// An assignment operator which joins this RevPtr to the other RevPtr.
87  /** @param other The source RevPtr to assign here.
88  */
89  inline RevPtr& operator= (const RevPtr<T> &other) {
90  helper->Del();
91 
92  other.helper->Add();
93  helper = other.helper;
94  auto_revoke = false;
95 
96  return *this;
97  }
98 
99 
100  /// Destructor which revokes the pointer only if AutoRevoke() was used
101  /// on this object.
103  if (auto_revoke) {
104  helper->Revoke();
105  }
106 
107  helper->Del();
108  }
109 
110 
111  /// Manually delete the object pointed to by this RevPtr, and revoke
112  /// the pointer for all shared RevPtr's.
113  /** Note: While this NULLs all the linked RevPtr's, it cannot affect
114  * raw pointers which have already been extracted or are in use when
115  * this is called. Be mindful of this in threading architecture design.
116  */
117  inline void Delete() {
118  helper->Delete();
119  }
120 
121 
122  /// Manually revoke the pointer, setting it equal to NULL for all shared
123  /// RevPtr objects.
124  /** This does not delete the pointer.
125  */
126  inline void Revoke() {
127  helper->Revoke();
128  }
129 
130 
131  /// Set this RevPtr to revoke the pointer upon deletion or leaving scope.
132  /** @param new_auto_revoke True if this RevPtr should automatically
133  * revoke.
134  * The recommended way to use this feature is to place the primary RevPtr
135  * in scope with the object to which it points so that they are deleted
136  * together, and then call AutoRevoke() on that RevPtr. Then all other
137  * RevPtr's which have been assigned or copy constructed from the primary
138  * RevPtr will be automatically revoked when it is destructed, and they
139  * will all return true for IsNull or throw exceptions if dereferencing
140  * is attempted.
141  */
142  inline void AutoRevoke(bool new_auto_revoke=true) {
143  auto_revoke = new_auto_revoke;
144  }
145 
146 
147 #include "PtrSharedCommon.h"
148 #include "PtrCommon.h"
149 
150 
151  protected:
152  /// @cond PROTECTED
153 
154  PtrHelper *helper;
155  bool auto_revoke;
156  /// @endcond
157  };
158 
159 
161 
162  /// Create a new RevPtr<T> constructed with the given arguments.
163  template<class T, class... Args>
164  RevPtr<T> MakeRevPtr(Args&&... args) {
165  return RevPtr<T>(new T(std::forward<Args>(args)...));
166  }
167 }
168 
169 
170 #endif // RC_REVPTR_H
171 
Provides informative exception handling.
Provides a set of convenience macros for metaprogramming and debugging.
#define RC_STREAM_RAWWRAP(Type)
Provides stream output for a class via Raw.
Definition: Macros.h:270
Common components for the *Ptr.h files. Do not include this directly.
Common components for the shared *Ptr.h files. Do not include directly.
Provides typedefs and routines for working with primitives.
A reference counting ptr that auto-deletes what it points to when the last copy leaves scope or is ot...
Definition: APtr.h:39
A safe pointer class that throws an RC::ErrorMsgNull if a null dereference is attempted.
Definition: Ptr.h:31
A reference counting pointer that revokes (NULLs) all copies when one set to AutoRevoke(true) leaves ...
Definition: RevPtr.h:45
RevPtr(const RevPtr< T > &other)
Copy constructor.
Definition: RevPtr.h:59
void Delete()
Manually delete the object pointed to by this RevPtr, and revoke the pointer for all shared RevPtr's.
Definition: RevPtr.h:117
RevPtr(const APtr< T > &other)
A conversion constructor which creates a new RevPtr from an APtr of the same or a derived type.
Definition: RevPtr.h:80
RevPtr & operator=(const RevPtr< T > &other)
An assignment operator which joins this RevPtr to the other RevPtr.
Definition: RevPtr.h:89
void Revoke()
Manually revoke the pointer, setting it equal to NULL for all shared RevPtr objects.
Definition: RevPtr.h:126
void AutoRevoke(bool new_auto_revoke=true)
Set this RevPtr to revoke the pointer upon deletion or leaving scope.
Definition: RevPtr.h:142
~RevPtr()
Destructor which revokes the pointer only if AutoRevoke() was used on this object.
Definition: RevPtr.h:102
RevPtr(const Ptr< T > &other)
A conversion constructor which creates a new RevPtr from a Ptr of the same or a derived type.
Definition: RevPtr.h:70
RevPtr(T *t_ptr=NULL)
Default constructor assigning the value of the pointer.
Definition: RevPtr.h:51
Definition: APtr.h:25
RevPtr< T > MakeRevPtr(Args &&... args)
Create a new RevPtr<T> constructed with the given arguments.
Definition: RevPtr.h:164
email address
— (c) 2015