You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As with `std::shared_ptr`/`std::weak_ptr`, if you need to obtain an observer pointer to an object when you only have `this` (i.e., from a member function), you can inherit from `oup::enable_observer_from_this<T>` to gain access to the `observer_from_this()` member function. This function will return a valid observer pointer as long as the object is owned by a unique or sealed pointer, and will return `nullptr` in all other cases. Contrary to `std::enable_shared_from_this<T>`, this feature naturally supports multiple inheritance.
88
+
89
+
## enable_observer_from_this
90
+
91
+
As with `std::shared_ptr`/`std::weak_ptr`, if you need to obtain an observer pointer to an object when you only have `this` (i.e., from a member function), you can inherit from `oup::enable_observer_from_this_unique<T>` or `oup::enable_observer_from_this_sealed<T>` (depending on the type of the owner pointer) to gain access to the `observer_from_this()` member function. Contrary to `std::enable_shared_from_this<T>`, this function is `noexcept` and is able to return a valid observer pointer at all times, even if the object is being constructed or is not owned by a unique or sealed pointer. Also contrary to `std::enable_shared_from_this<T>`, this feature naturally supports multiple inheritance.
92
+
93
+
To achieve this, the price to pay is that `oup::enable_observer_from_this_unique<T>` uses virtual inheritance, while `oup::enable_observer_from_this_sealed<T>` requires `T`'s constructor to take a control block as input (thereby preventing `T` from being default-constructible, copiable, or movable). If needed, these trade-offs can be controlled by policies, see below.
94
+
95
+
96
+
## Policies
97
+
98
+
Similarly to `std::string` and `std::basic_string`, this library provides both "convenience" types (`oup::observable_unique_ptr<T,Deleter>`, `oup::observable_sealed_ptr<T>`, `oup::observer_ptr<T>`, `oup::enable_observable_from_this_unique<T>`, `oup::enable_observable_from_this_sealed<T>`) and "generic" types (`oup::basic_observable_ptr<T,Deleter,Policy>`, `oup::basic_observer_ptr<T,ObsPolicy>`, `oup::basic_enable_observable_from_this<T,Policy>`).
99
+
100
+
If the trade-offs chosen to defined the "convenience" types are not appropriate for your use cases, they can be fine-tuned using the generic classes and providing your own choice of policies. Please refer to the documentation for more information on policies. In particular, policies will control most of the API and behavior of the `enable_observable_from_this` feature, as well as allowing you to tune the size of the reference counting object (speed/memory trade-off).
87
101
88
102
89
103
## Limitations
@@ -117,23 +131,25 @@ Labels:
117
131
| Support arrays | yes | yes | no | yes | yes | no | no |
118
132
| Support custom allocator | N/A | yes | no | yes | yes | no | no |
119
133
| Support custom deleter | N/A | N/A | N/A | yes | yes(4) | yes | no |
120
-
| Number of heap alloc. | 0 | 0 | 0 | 1 | 1/2(5) | 2 | 1 |
134
+
| Max number of observers | inf. | ?(5) | 2^31 - 1 | 1 | ?(5) | 1 | 1 |
135
+
| Number of heap alloc. | 0 | 0 | 0 | 1 | 1/2(6) | 2 | 1 |
- (1) If `expired()` returns true, the pointer is guaranteed to remain `nullptr` forever, with no race condition. If `expired()` returns false, the pointer could still expire on the next instant, which can lead to race conditions.
133
148
- (2) By construction, only one thread can own the pointer, therefore deletion is thread-safe.
134
149
- (3) Yes if using `std::atomic<std::shared_ptr<T>>` and `std::atomic<std::weak_ptr<T>>`.
135
150
- (4) Not if using `std::make_shared()`.
136
-
- (5) 2 by default, or 1 if using `std::make_shared()`.
151
+
- (5) Not defined by the C++ standard. In practice, libstdc++ stores its reference count on an `_Atomic_word`, which for a common 64bit linux platform is a 4 byte signed integer, hence the limit will be 2^31 - 1. Microsoft's STL uses `_Atomic_counter_t`, which for a 64bit Windows platform is 4 bytes unsigned integer, hence the limit will be 2^32 - 1.
152
+
- (6) 2 by default, or 1 if using `std::make_shared()`.
137
153
138
154
139
155
## Speed benchmarks
@@ -152,6 +168,8 @@ Detail of the benchmarks:
152
168
- Create observer copy: construct a new observer pointer from another observer pointer.
153
169
- Dereference observer: get a reference to the underlying object from an observer pointer.
0 commit comments