StaticCastSharedRef

SharedPointerInternals.h contains the implementation of reference counting structures we need.

Windows
MacOS
Linux

References

Module

Core

Header

/Engine/Source/Runtime/Core/Public/Templates/SharedPointer.h

Include

#include "Templates/SharedPointer.h"

Syntax

template<class CastToType, class CastFromType, ESPMode Mode>
TSharedRef< CastToType, Mode > StaticCastSharedRef
(
    TSharedRef< CastFromType, Mode > const & InSharedRef
)

Remarks

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.

  1. 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*.

  2. Shared pointers have minimal overhead. All operations are constant-time. Robust features. Supports 'const', forward declarations to incomplete types, type-casting, etc.

  3. 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.

Parameters

Parameter

Description

InSharedRef

The shared reference to cast

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss