StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
pointers.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This is the base for StormByte Suite libraries.
5 *
6 * StormByte original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte source in this repository.
20 * They do not cover other StormByte modules or any third-party material
21 * shipped with this repository (including everything under thirdparty/),
22 * which remains under its own license.
23 *
24 * Neither license grants any patent rights. Any patent licenses required
25 * to use this software or third-party components must be obtained separately
26 * from the patent holders.
27 *
28 * StormByte is distributed in the hope that it will be useful,
29 * but WITHOUT ANY WARRANTY; without even the implied warranty of
30 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 * GNU Lesser General Public License for more details.
32 *
33 * You should have received a copy of the GNU Lesser General Public License
34 * version 3 along with StormByte. If not, see
35 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
36 *
37 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
38 */
39
40#pragma once
41
46
47#include <atomic>
48#include <compare>
49#include <cstddef>
50#include <cstdint>
51#include <memory>
52#include <new>
53#include <type_traits>
54#include <utility>
55
60namespace StormByte {
65 namespace Safe {
66 template<class T>
67 class Shared;
68
69 template<class T>
70 class Unique;
71
72 template<class T>
73 class Weak;
74
75 template<class T>
76 class AtomicShared;
77
78 template<class T>
80
87 namespace Heap {
92 void (*destroy)(void*) noexcept = nullptr;
93
99 template<class U>
100 void operator()(U* pointer) const noexcept {
101 if (destroy != nullptr)
102 destroy(pointer);
103 }
104 };
105 }
106
111 namespace Detail {
117 struct Control {
118 std::atomic<long> Strong;
119 std::atomic<long> Weak;
120 void (*Destroy)(Control*) noexcept;
121 void* Object;
122 };
123 }
124
132 template<class T>
134 public:
135 using element_type = T;
137
141 Shared() noexcept;
142
147 Shared(std::nullptr_t null) noexcept;
148
154 template<class U>
155 requires Type::ConvertibleTo<U*, T*>
156 Shared(const Shared<U>& other) noexcept;
157
163 template<class U>
164 requires Type::ConvertibleTo<U*, T*>
165 Shared(Shared<U>&& other) noexcept;
166
171 Shared(const Shared& other) noexcept;
172
177 Shared(Shared&& other) noexcept;
178
184 explicit Shared(const Weak<T>& weak);
185
191 Shared& operator=(const Shared& other) noexcept;
192
198 Shared& operator=(Shared&& other) noexcept;
199
204
209 T* get() const noexcept;
210
215 std::add_lvalue_reference_t<T> operator*() const noexcept;
216
221 T* operator->() const noexcept;
222
227 explicit operator bool() const noexcept;
228
233 long use_count() const noexcept;
234
238 void reset() noexcept;
239
244 void swap(Shared& other) noexcept;
245
252 template<class U>
253 bool owner_before(const Shared<U>& other) const noexcept;
254
261 template<class U>
262 bool owner_before(const Weak<U>& other) const noexcept;
263
272 template<class Target, class... Args>
273 requires Type::SameAs<Target, T> || Type::DerivedFrom<Target, T>
274 static Shared<T> MakePointer(Args&&... args);
275
280 STORMBYTE_FORCE_INLINE explicit operator std::shared_ptr<T>() const {
281 if (m_control == nullptr)
282 return {};
283 m_control->Strong.fetch_add(1, std::memory_order_relaxed);
284 Detail::Control* control = m_control;
285 return std::shared_ptr<T>(m_object, [control](T*) noexcept {
286 if (control->Strong.fetch_sub(1, std::memory_order_acq_rel) == 1) {
287 control->Destroy(control);
288 if (control->Weak.fetch_sub(1, std::memory_order_acq_rel) == 1)
289 Heap::Free(control);
290 }
291 });
292 }
293
294 private:
300 Shared(Detail::Control* control, T* object) noexcept;
301
305 void Release() noexcept;
306
307 template<class U>
308 friend class Shared;
309
310 template<class U>
311 friend class Weak;
312
313 template<class U>
314 friend class AtomicShared;
315
316 template<class U, class... Args>
317 friend Shared<U> MakeShared(Args&&...);
318
319 template<class X, class Y>
320 friend Shared<X> StaticPointerCast(const Shared<Y>&) noexcept;
321
322 template<class X, class Y>
323 friend Shared<X> DynamicPointerCast(const Shared<Y>&) noexcept;
324
325 template<class X, class Y>
326 friend Shared<X> ConstPointerCast(const Shared<Y>&) noexcept;
327
328 template<class X, class Y>
329 friend Shared<X> ReinterpretPointerCast(const Shared<Y>&) noexcept;
330
331 Detail::Control* m_control;
332 T* m_object;
333 };
334
342 template<class T>
344 public:
345 using element_type = T;
346 using pointer = T*;
348
352 Unique() noexcept;
353
358 Unique(std::nullptr_t null) noexcept;
359
365 template<class U>
366 requires Type::ConvertibleTo<U*, T*>
367 Unique(Unique<U>&& other) noexcept;
368
373 Unique(const Unique& other) = delete;
374
379 Unique(Unique&& other) noexcept;
380
386 Unique& operator=(const Unique& other) = delete;
387
393 Unique& operator=(Unique&& other) noexcept;
394
399
404 T* get() const noexcept;
405
410 std::add_lvalue_reference_t<T> operator*() const noexcept;
411
416 T* operator->() const noexcept;
417
422 explicit operator bool() const noexcept;
423
427 void reset() noexcept;
428
433 void swap(Unique& other) noexcept;
434
443 template<class Target, class... Args>
444 requires Type::SameAs<Target, T> || Type::DerivedFrom<Target, T>
445 static Unique<T> MakePointer(Args&&... args);
446
451 STORMBYTE_FORCE_INLINE operator std::unique_ptr<T, Heap::ObjectDeleter>() && noexcept {
452 Heap::ObjectDeleter deleter{m_destroy};
453 T* object = m_object;
454 m_object = nullptr;
455 m_destroy = nullptr;
456 return std::unique_ptr<T, Heap::ObjectDeleter>(object, deleter);
457 }
458
459 private:
465 Unique(T* object, void (*destroy)(void*) noexcept) noexcept;
466
467 template<class U>
468 friend class Unique;
469
470 template<class U, class... Args>
471 friend Unique<U> MakeUnique(Args&&...);
472
473 T* m_object;
474 void (*m_destroy)(void*) noexcept;
475 };
476
484 template<class T>
486 public:
487 using element_type = T;
488
492 Weak() noexcept;
493
498 Weak(std::nullptr_t null) noexcept;
499
505 template<class U>
506 requires Type::ConvertibleTo<U*, T*>
507 Weak(const Shared<U>& owner) noexcept;
508
513 Weak(const Weak& other) noexcept;
514
519 Weak(Weak&& other) noexcept;
520
526 Weak& operator=(const Weak& other) noexcept;
527
533 Weak& operator=(Weak&& other) noexcept;
534
539
544 Shared<T> lock() const noexcept;
545
550 bool expired() const noexcept;
551
556 long use_count() const noexcept;
557
561 void reset() noexcept;
562
567 void swap(Weak& other) noexcept;
568
575 template<class U>
576 bool owner_before(const Weak<U>& other) const noexcept;
577
584 template<class U>
585 bool owner_before(const Shared<U>& other) const noexcept;
586
587 private:
591 void Release() noexcept;
592
593 template<class U>
594 friend class Weak;
595
596 template<class U>
597 friend class Shared;
598
599 template<class U>
601
602 Detail::Control* m_control;
603 T* m_object;
604 };
605
613 template<class T>
615 public:
619 EnableSharedFromThis() noexcept = default;
620
626
632
638 EnableSharedFromThis& operator=(const EnableSharedFromThis& other) noexcept;
639
645 EnableSharedFromThis& operator=(EnableSharedFromThis&& other) noexcept;
646
651
652 protected:
659
660 private:
661 template<class U, class... Args>
662 friend Shared<U> MakeShared(Args&&...);
663
664 mutable Weak<T> m_weak;
665 };
666
674 template<class T>
676 public:
680 AtomicShared() noexcept;
681
686 explicit AtomicShared(Shared<T> owner) noexcept;
687
692 AtomicShared(const AtomicShared& other) = delete;
693
698
704 AtomicShared& operator=(const AtomicShared& other) = delete;
705
711 AtomicShared& operator=(Shared<T> owner) noexcept;
712
717 explicit operator bool() const noexcept;
718
723 Shared<T> load() const noexcept;
724
729 void store(Shared<T> owner) noexcept;
730
736 Shared<T> exchange(Shared<T> owner) noexcept;
737
744 bool compare_exchange_strong(Shared<T>& expected, Shared<T> desired) noexcept;
745
752 bool compare_exchange_weak(Shared<T>& expected, Shared<T> desired) noexcept;
753
754 private:
758 void Lock() const noexcept;
759
763 void Unlock() const noexcept;
764
765 mutable std::atomic_flag m_lock;
766 Detail::Control* m_control;
767 T* m_object;
768 };
769
778 template<class T, class... Args>
779 Shared<T> MakeShared(Args&&... args);
780
789 template<class T, class... Args>
790 Unique<T> MakeUnique(Args&&... args);
791
799 template<class T, class U>
800 Shared<T> StaticPointerCast(const Shared<U>& from) noexcept;
801
809 template<class T, class U>
810 Shared<T> DynamicPointerCast(const Shared<U>& from) noexcept;
811
819 template<class T, class U>
820 Shared<T> ConstPointerCast(const Shared<U>& from) noexcept;
821
829 template<class T, class U>
830 Shared<T> ReinterpretPointerCast(const Shared<U>& from) noexcept;
831
840 template<class T, class U>
841 STORMBYTE_FORCE_INLINE bool operator==(const Shared<T>& left, const Shared<U>& right) noexcept {
842 return left.get() == right.get();
843 }
844
853 template<class T, class U>
854 STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(const Shared<T>& left, const Shared<U>& right) noexcept {
855 return std::compare_three_way{}(left.get(), right.get());
856 }
857
865 template<class T>
866 STORMBYTE_FORCE_INLINE bool operator==(const Shared<T>& left, std::nullptr_t null) noexcept {
867 return left.get() == null;
868 }
869
877 template<class T>
878 STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(const Shared<T>& left, std::nullptr_t null) noexcept {
879 return std::compare_three_way{}(left.get(), static_cast<T*>(null));
880 }
881
890 template<class T, class U>
891 STORMBYTE_FORCE_INLINE bool operator==(const Unique<T>& left, const Unique<U>& right) noexcept {
892 return left.get() == right.get();
893 }
894
903 template<class T, class U>
904 STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(const Unique<T>& left, const Unique<U>& right) noexcept {
905 return std::compare_three_way{}(left.get(), right.get());
906 }
907
915 template<class T>
916 STORMBYTE_FORCE_INLINE bool operator==(const Unique<T>& left, std::nullptr_t null) noexcept {
917 return left.get() == null;
918 }
919
927 template<class T>
928 STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(const Unique<T>& left, std::nullptr_t null) noexcept {
929 return std::compare_three_way{}(left.get(), static_cast<T*>(null));
930 }
931
938 template<class T>
939 void swap(Shared<T>& left, Shared<T>& right) noexcept;
940
947 template<class T>
948 void swap(Unique<T>& left, Unique<T>& right) noexcept;
949
956 template<class T>
957 void swap(Weak<T>& left, Weak<T>& right) noexcept;
958 }
959}
960
961template<class T>
968 STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Shared<T>& value) const noexcept {
969 return Hash<T*>{}(value.get());
970 }
971};
972
973template<class T>
980 STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Unique<T>& value) const noexcept {
981 return Hash<T*>{}(value.get());
982 }
983};
984
985template<class T>
992 STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Weak<T>& value) const noexcept {
993 return Hash<T*>{}(value.lock().get());
994 }
995};
996
997template<class T>
998struct std::hash<StormByte::Safe::Shared<T>> {
1004 std::size_t operator()(const StormByte::Safe::Shared<T>& value) const noexcept {
1006 }
1007};
1008
1009template<class T>
1010struct std::hash<StormByte::Safe::Unique<T>> {
1016 std::size_t operator()(const StormByte::Safe::Unique<T>& value) const noexcept {
1018 }
1019};
1020
1021template<class T>
1022struct std::hash<StormByte::Safe::Weak<T>> {
1028 std::size_t operator()(const StormByte::Safe::Weak<T>& value) const noexcept {
1030 }
1031};
1032
Atomic publication of a Shared.
Definition pointers.hxx:675
Shared< T > exchange(Shared< T > owner) noexcept
Replace the published owner and return the previous one.
AtomicShared() noexcept
Construct an empty atomic owner.
bool compare_exchange_weak(Shared< T > &expected, Shared< T > desired) noexcept
Replace the published owner when it compares equal by address.
bool compare_exchange_strong(Shared< T > &expected, Shared< T > desired) noexcept
Replace the published owner when it compares equal by address.
Shared< T > load() const noexcept
Copy the published owner.
void store(Shared< T > owner) noexcept
Replace the published owner.
Base that can recover a Shared from an object owned by one.
Definition pointers.hxx:614
Shared< T > SharedFromThis() const
Recover an owner of this object.
friend Shared< U > MakeShared(Args &&...)
EnableSharedFromThis() noexcept=default
Construct an unlinked base.
Forward declaration of shared ownership.
Definition pointers.hxx:133
friend Shared< X > ConstPointerCast(const Shared< Y > &) noexcept
friend Shared< X > ReinterpretPointerCast(const Shared< Y > &) noexcept
friend Shared< X > DynamicPointerCast(const Shared< Y > &) noexcept
friend class AtomicShared
Definition pointers.hxx:314
void swap(Shared &other) noexcept
Exchange owners.
Weak< T > weak_type
Matching observer.
Definition pointers.hxx:136
friend Shared< X > StaticPointerCast(const Shared< Y > &) noexcept
Shared() noexcept
Construct an empty owner.
bool owner_before(const Shared< U > &other) const noexcept
Order control blocks by identity.
friend class Shared
Definition pointers.hxx:308
void reset() noexcept
Drop this owner.
friend Shared< U > MakeShared(Args &&...)
T element_type
Pointee type.
Definition pointers.hxx:135
static Shared< T > MakePointer(Args &&... args)
Allocate Target on Base's heap and own it as T.
long use_count() const noexcept
Return the number of owners.
friend class Weak
Definition pointers.hxx:311
T * get() const noexcept
Return the stored pointer.
Forward declaration of unique ownership.
Definition pointers.hxx:343
T element_type
Pointee type.
Definition pointers.hxx:345
void reset() noexcept
Destroy the object and leave this owner empty.
friend Unique< U > MakeUnique(Args &&...)
T * get() const noexcept
Return the stored pointer.
Heap::ObjectDeleter deleter_type
Deleter used by the STL conversion.
Definition pointers.hxx:347
void swap(Unique &other) noexcept
Exchange owners.
friend class Unique
Definition pointers.hxx:468
static Unique< T > MakePointer(Args &&... args)
Allocate Target on Base's heap and own it as T.
Unique() noexcept
Construct an empty owner.
T * pointer
Stored pointer.
Definition pointers.hxx:346
Forward declaration of weak ownership.
Definition pointers.hxx:485
void swap(Weak &other) noexcept
Exchange observers.
Weak() noexcept
Construct an empty observer.
void reset() noexcept
Drop this observer.
bool expired() const noexcept
Test whether the object is already gone.
friend class Shared
Definition pointers.hxx:597
Shared< T > lock() const noexcept
Lock the control block.
friend class EnableSharedFromThis
Definition pointers.hxx:600
long use_count() const noexcept
Return the number of owners.
bool owner_before(const Weak< U > &other) const noexcept
Order control blocks by identity.
T element_type
Pointee type.
Definition pointers.hxx:487
friend class Weak
Definition pointers.hxx:594
Private Base heap used by StormByte::Safe::Shared, StormByte::Safe::Unique and StormByte::Safe::Clona...
Private helpers.
Allocate and free raw blocks on Base's heap.
void Free(void *pointer) noexcept
Release a block obtained from Allocate.
Owned values that cross a DLL without the caller's CRT.
bool operator==(std::span< const std::byte > bytes, const Binary &data) noexcept
Equality of a span against a sequence.
Definition binary.hxx:770
Shared< T > MakeShared(Args &&... args)
Construct T on Base's heap and share it.
Shared< T > ReinterpretPointerCast(const Shared< U > &from) noexcept
reinterpret_cast of the stored pointer.
Shared< T > ConstPointerCast(const Shared< U > &from) noexcept
const_cast of the stored pointer.
constexpr First & get(Pair< First, Second > &pair) noexcept
Access the first pair member.
void swap(Binary &left, Binary &right) noexcept
Exchange two sequences.
Definition binary.hxx:760
Unique< T > MakeUnique(Args &&... args)
Construct T on Base's heap and own it.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=>(std::span< const std::byte > bytes, const Binary &data) noexcept
Three-way comparison of a span against a sequence.
Definition binary.hxx:790
Shared< T > StaticPointerCast(const Shared< U > &from) noexcept
static_cast of the stored pointer.
Shared< T > DynamicPointerCast(const Shared< U > &from) noexcept
dynamic_cast of the stored pointer.
@ Release
Release.
Definition memory_order.hxx:64
Root namespace of the StormByte suite.
Octet count. Defined in byte_size.hxx. Forwarded so Type::Numeral can name it.
STL namespace.
#define STORMBYTE_FORCE_INLINE
Definition platform.h:134
Base-owned reference counts and the real destructor.
Definition pointers.hxx:117
void(* Destroy)(Control *) noexcept
Destructor of the concrete object.
Definition pointers.hxx:120
void * Object
Address of the concrete object inside this block.
Definition pointers.hxx:121
std::atomic< long > Weak
Owners plus observers. Zero frees the block.
Definition pointers.hxx:119
std::atomic< long > Strong
Owners. Zero destroys the object.
Definition pointers.hxx:118
STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Shared< T > &value) const noexcept
Hash the stored address.
Definition pointers.hxx:968
STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Unique< T > &value) const noexcept
Hash the stored address.
Definition pointers.hxx:980
STORMBYTE_FORCE_INLINE std::size_t operator()(const StormByte::Safe::Weak< T > &value) const noexcept
Hash the observed address.
Definition pointers.hxx:992
Cross-module hash.
Definition hash.hxx:95
Destroy the concrete object and return its block to Free.
Definition pointers.hxx:91
void operator()(U *pointer) const noexcept
Destroy pointer with the concrete destructor.
Definition pointers.hxx:100
void(* destroy)(void *) noexcept
Concrete destructor stored by Unique.
Definition pointers.hxx:92
std::size_t operator()(const StormByte::Safe::Shared< T > &value) const noexcept
Hash the stored address.
Definition pointers.hxx:1004
std::size_t operator()(const StormByte::Safe::Unique< T > &value) const noexcept
Hash the stored address.
Definition pointers.hxx:1016
std::size_t operator()(const StormByte::Safe::Weak< T > &value) const noexcept
Hash the observed address.
Definition pointers.hxx:1028
#define STORMBYTE_PUBLIC_TYPE
Definition visibility.h:57