SharedPointer - Unreal smart pointer library
This is a smart pointer library consisting of shared references (TSharedRef), shared pointers (TSharedPtr), weak pointers (TWeakPtr) as well as related helper functions and classes. This implementation is modeled after the C++0x standard library's shared_ptr as well as Boost smart pointers.
Benefits of using shared references and pointers:
Clean syntax. You can copy, dereference and compare shared pointers just like regular C++ pointers.
Prevents memory leaks. Resources are destroyed automatically when there are no more shared references.
Weak referencing. Weak pointers allow you to safely check when an object has been destroyed.
Thread safety. Includes "thread safe" version that can be safely accessed from multiple threads.
Ubiquitous. You can create shared pointers to virtually *any* type of object.
Runtime safety. Shared references are never null and can always be dereferenced.
No reference cycles. Use weak pointers to break reference cycles.
Confers intent. You can easily tell an object *owner* from an *observer*.
Performance. Shared pointers have minimal overhead. All operations are constant-time.
Robust features. Supports 'const', forward declarations to incomplete types, type-casting, etc.
Memory. Only twice the size of a C++ pointer in 64-bit (plus a shared 16-byte reference controller.)
This library contains the following smart pointers:
TSharedRef - Non-nullable, reference counted non-intrusive authoritative smart pointer
TSharedPtr - Reference counted non-intrusive authoritative smart pointer
TWeakPtr - Reference counted non-intrusive weak pointer reference
Additionally, the following helper classes and functions are defined:
MakeShareable() - Used to initialize shared pointers from C++ pointers (enables implicit conversion)
MakeShared<T>(...) - Used to construct a T alongside its controller, saving an allocation.
TSharedFromThis - You can derive your own class from this to acquire a TSharedRef from "this"
StaticCastSharedRef() - Static cast utility function, typically used to downcast to a derived type.
ConstCastSharedRef() - Converts a 'const' reference to 'mutable' smart reference
StaticCastSharedPtr() - Dynamic cast utility function, typically used to downcast to a derived type.
ConstCastSharedPtr() - Converts a 'const' smart pointer to 'mutable' smart pointer
StaticCastWeakPtr() - Dynamic cast utility function, typically used to downcast to a derived type.
ConstCastWeakPtr() - Converts a 'const' smart pointer to 'mutable' smart pointer
Examples:
Tips:
- Use TSharedRef instead of TSharedPtr whenever possible – it can never be nullptr!
- You can call TSharedPtr::Reset() to release a reference to your object (and potentially deallocate)
- Use the MakeShareable() helper function to implicitly convert to TSharedRefs or TSharedPtrs
- Prefer MakeShared<T>(...) to MakeShareable(new T(...))
- You can never reset a TSharedRef or assign it to nullptr, but you can assign it a new object
- Shared pointers assume ownership of objects – no need to call delete yourself!
- Usually you should "operator new" when passing a C++ pointer to a new shared pointer
- Use TSharedRef or TSharedPtr when passing smart pointers as function parameters, not TWeakPtr
- The "thread-safe" versions of smart pointers are a bit slower – only use them when needed
- You can forward declare shared pointers to incomplete types, just how you'd expect to!
- Shared pointers of compatible types will be converted implicitly (e.g. upcasting)
- You can create a typedef to TSharedRef< MyClass > to make it easier to type
- For best performance, minimize calls to TWeakPtr::Pin (or conversions to TSharedRef/TSharedPtr)
- Your class can return itself as a shared reference if you derive from TSharedFromThis
- To downcast a pointer to a derived object class, use the StaticCastSharedRef, StaticCastSharedRef or StaticCastWeakPtr functions
- 'const' objects are fully supported with shared pointers!
- You can make a 'const' pointer mutable using the ConstCastSharedRef, ConstCastSharedPtr or ConstCastWeakPtr functions
Limitations:
- Shared pointers are not compatible with Unreal objects (UObject classes)!
- Currently only types with that have regular destructors (no custom deleters)
- Dynamically-allocated arrays are not supported yet (e.g. MakeShareable( new int32[20] ))
Differences from other implementations (e.g. boost:shared_ptr, std::shared_ptr):
- Type names and method names are more consistent with Unreal's codebase
- You must use Pin() to convert weak pointers to shared pointers (no explicit constructor)
- Thread-safety features are optional instead of forced
- TSharedFromThis returns a shared *reference*, not a shared *pointer*
- Some features were omitted (e.g. use_count(), unique(), etc.)
- No exceptions are allowed (all related features have been omitted)
- Custom allocators and custom delete functions are not supported yet
- Our implementation supports non-nullable smart pointers (TSharedRef)
- Several other new features added, such as MakeShareable and nullptr assignment
Why did we write our own Unreal shared pointer instead of using available alternatives?
- std::shared_ptr (and even tr1::shared_ptr) is not yet available on all platforms
- Allows for a more consistent implementation on all compilers and platforms
- Can work seamlessly with other Unreal containers and types
- Better control over platform specifics, including threading and optimizations
- We want thread-safety features to be optional (for performance)
- We've added our own improvements (MakeShareable, assign to nullptr, etc.)
- Exceptions were not needed nor desired in our implementation
- We wanted more control over performance (inlining, memory, use of virtuals, etc.)
- Potentially easier to debug (liberal code comments, etc.)
- Prefer not to introduce new third party dependencies when not needed
Casts a shared reference of one type to another type. (static_cast) Useful for down-casting.
- Parameters
-
| InSharedRef | The shared reference to cast |
- Examples
- /work/Engine/Source/Runtime/UMG/Public/Components/Widget.h.
1.9.8