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
This is a small header-only library, providing a unique-ownership smart pointer`observable_unique_ptr` that can be observed with non-owning pointers `observer_ptr`. It is a mixture of `std::unique_ptr` and `std::shared_ptr`: it borrows the unique-ownership semantic of `std::unique_ptr` (movable, non-copiable), but allows creating `observer_ptr` to monitor the lifetime of the pointed object (like `std::weak_ptr` for `std::shared_ptr`).
14
+
This is a small header-only library, providing the unique-ownership smart pointers`observable_unique_ptr`and `observable_sealed_ptr`that can be observed with non-owning pointers `observer_ptr`. This is a mixture of `std::unique_ptr` and `std::shared_ptr`: it borrows the unique-ownership semantic of `std::unique_ptr` (movable, non-copiable), but allows creating `observer_ptr` to monitor the lifetime of the pointed object (like `std::weak_ptr` for `std::shared_ptr`).
8
15
9
-
This is useful for cases where the shared-ownership of `std::shared_ptr` is not desirable, e.g., when lifetime must be carefully controlled and not be allowed to extend, yet non-owning/weak/observer references to the object may exist after the object has been deleted.
16
+
The only difference between `observable_unique_ptr` and `observable_sealed_ptr` is that the former can release ownership, while the latter cannot. Disallowing release of ownership enables allocation optimizations. Therefore, the recommendation is to use `observable_sealed_ptr` unless release of ownership is required.
10
17
11
-
Note: Because of the unique ownership model, observer pointers cannot extend the lifetime of the pointed object, hence `observable_unique_ptr`/`observer_ptr` provides less thread-safety compared to `std::shared_ptr`/`std::weak_ptr`. This is also true of `std::unique_ptr`, and is a fundamental limitation of unique ownership. If this is an issue, you will need either to add your own explicit locking logic, or use `std::shared_ptr`/`std::weak_ptr`.
18
+
These pointers are useful for cases where the shared-ownership of `std::shared_ptr` is not desirable, e.g., when lifetime must be carefully controlled and not be allowed to extend, yet non-owning/weak/observer references to the object may exist after the object has been deleted.
19
+
20
+
Note: Because of the unique ownership model, observer pointers cannot extend the lifetime of the pointed object, hence this library provides less thread-safety compared to `std::shared_ptr`/`std::weak_ptr`. This is also true of `std::unique_ptr`, and is a fundamental limitation of unique ownership. If this is an issue, you will need either to add your own explicit locking logic, or use `std::shared_ptr`/`std::weak_ptr`.
12
21
13
22
14
23
## Usage
15
24
16
25
This is a header-only library requiring a C++17-compliant compiler. You have multiple ways to set it up:
17
-
- just include this repository as a submodule in your own git repository and use CMake `add_subdirectory`,
18
-
- use CMake `FetchContent`,
26
+
- just include this repository as a submodule in your own git repository and use CMake `add_subdirectory` (or use CMake `FetchContent`), then link with `target_link_libraries(<your-target> PUBLIC oup::oup)`.
19
27
- download the header and include it in your own sources.
20
28
21
29
From there, include the single header `<oup/observable_unique_ptr.hpp>`, and directly use the smart pointer in your own code:
@@ -33,7 +41,7 @@ int main() {
33
41
34
42
{
35
43
// Unique pointer that owns the object
36
-
auto owner_ptr = oup::make_observable_unique<std::string>("hello");
44
+
auto owner_ptr = oup::make_observable_sealed<std::string>("hello");
37
45
38
46
// Make the observer pointer point to the object
39
47
obs_ptr = owner_ptr;
@@ -64,20 +72,84 @@ int main() {
64
72
65
73
## Limitations
66
74
67
-
The follownig limitations are features that were not implemented simply because of lack of motivation.
68
-
69
-
-`observable_unique_ptr` does not support pointers to arrays, but `std::unique_ptr` and `std::shared_ptr` both do.
70
-
-`observable_unique_ptr` does not support custom allocators, but `std::shared_ptr` does.
75
+
The following limitations are features that were not implemented simply because of lack of motivation.
76
+
77
+
- this library does not support pointers to arrays, but `std::unique_ptr` and `std::shared_ptr` both do.
78
+
- this library does not support custom allocators, but `std::shared_ptr` does.
79
+
80
+
81
+
## Comparison spreadsheet
82
+
83
+
In this comparison spreadsheet, the raw pointer `T*` is assumed to never be owning, and used only to observe an existing object (which may or may not have been deleted). The stack and heap sizes were measured with gcc 9.3.0 and libstdc++.
- (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.
117
+
- (2) By construction, only one thread can own the pointer, therefore deletion is thread-safe.
118
+
- (3) Yes if using `std::atomic<std::shared_ptr<T>>` and `std::atomic<std::weak_ptr<T>>`.
119
+
- (4) Not if using `std::make_shared()`.
120
+
- (5) 2 by default, or 1 if using `std::make_shared()`.
121
+
122
+
123
+
## Speed benchmarks
124
+
125
+
Labels are the same as in the comparison spreadsheet. The speed benchmarks were compiled with gcc 9.3.0 and libstdc++, with all optimizations turned on (except LTO), and run on a linux (5.1.0-89) machine with a Ryzen 5 2600 CPU. Speed is measured relative to `std::unique_ptr<T>` used as owner pointer, and `T*` used as observer pointer, which should be the fastest possible implementation (but obviously the one with least safety).
126
+
127
+
You can run the benchmarks yourself, they are located in `tests/speed_benchmark.cpp`. The benchmark executable runs tests for three object types: `int`, `float`, `std::string`, and `std::array<int,65'536>`, to simulate objects of various allocation cost. The timings below are the worst-case values measured across all object types, which should be most relevant to highlight the overhead from the pointer itself (and erases flukes from the benchmarking framework). In real life scenarios, the actual measured overhead will be substantially lower, as actual business logic is likely to dominate the time budget.
- Create owner empty: default-construct an owner pointer (to nullptr).
142
+
- Create owner: construct an owner pointer by taking ownership of an object (for `oup::observer_sealed_ptr`, this is using `oup::make_observable_sealed()`).
143
+
- Create owner factory: construct an owner pointer using `std::make_*` or `oup::make_*` factory functions.
144
+
- Dereference owner: get a reference to the underlying owned object from an owner pointer.
145
+
- Create observer empty: default-construct an observer pointer (to nullptr).
146
+
- Create observer: construct an observer pointer from an owner pointer.
147
+
- Create observer copy: construct a new observer pointer from another observer pointer.
148
+
- Dereference observer: get a reference to the underlying object from an observer pointer.
71
149
72
150
73
151
## Notes
74
152
75
-
76
153
### Alternative implementation
77
154
78
155
An alternative implementation of an "observable unique pointer" can be found [here](https://www.codeproject.com/articles/1011134/smart-observers-to-use-with-unique-ptr). It does not compile out of the box with gcc unfortunately, but it does contain more features (like creating an observer pointer from a raw `this`) and lacks others (their `make_observable` always performs two allocations). Have a look to check if this better suits your needs.
79
-
80
-
81
-
### ABI compatibility
82
-
83
-
When compiled in C++20 mode, by default the implementation will attempt to optimize empty deleters. This is not ABI-compatible with previous versions of C++, which lack the `[[no_unique_address]]` attribute (introduced in C++20). If ABI compatibility with previous versions of C++ is a concern to you, please define the macro `OUP_CPP17_ABI_COMPAT` before including the header of this library. This will disable the empty deleter optimisation, and enable binary compatibility with older C++ versions.
0 commit comments