Module |
|
Header |
/Engine/Source/Runtime/Core/Public/Templates/SharedPointer.h |
Include |
#include "Templates/SharedPointer.h" |
template<class CastToType, class CastFromType, ESPMode Mode>
TSharedRef< CastToType, Mode > StaticCastSharedRef
(
TSharedRef< CastFromType, Mode > const & InSharedRef
)
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.
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*.
Shared pointers have minimal overhead. All operations are constant-time. Robust features. Supports 'const', forward declarations to incomplete types, type-casting, etc.
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) 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
Examples:
Please see 'SharedPointerTesting.inl' for various examples of shared pointers and references!
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
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, to the StaticCastSharedPtr function
'const' objects are fully supported with shared pointers!
You can make a 'const' shared pointer mutable using the ConstCastSharedPtr function
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. MakeSharable( new int32[20] ))
Implicit conversion of TSharedPtr/TSharedRef to bool is not supported yet
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.
Parameter |
Description |
---|---|
InSharedRef |
The shared reference to cast |