Shared References

Smart pointer type that cannot be uninitialized or assigned null.

Choose your operating system:

Windows

macOS

Linux

A Shared Reference is a strong, non-nullable Smart Pointer for data objects outside of the Engine's UObject system. This means you cannot reset a Shared Reference, assign a null object to it, or create an empty one. Because of this, Shared References always contain a valid object, and do not even have an IsValid method. When choosing between Shared References and Shared Pointers, Shared References are the preferred option unless you need an empty or nullable object. If you need potentially-empty or nullable references, you should use Shared Pointers instead.

Unlike a standard C++ reference, a Shared Reference can be reassigned to another object after creation.

Declaration and Initialization

Shared References are non-nullable, so intialization requires a data object. Attempting to create a Shared Reference without a valid object will not compile, and attempting to initialize a Shared Reference to a null pointer variable.

// Create a shared reference to a new node
TSharedRef<FMyObjectType> NewReference = MakeShared<FMyObjectType>();

Attempting to create a Shared Reference without a valid object will not compile:

// Neither of these will compile:
TSharedRef<FMyObjectType> UnassignedReference;
TSharedRef<FMyObjectType> NullAssignedReference = nullptr;
// This will compile, but will assert if NullObject is actually null.
TSharedRef<FMyObjectType> NullAssignedReference = NullObject;

Converting Between Shared Pointers and Shared References

Converting between Shared Pointers and Shared References is a common practice. Shared References implicitly convert to Shared Pointers, and provide the additional guarantee that the new Shared Pointer will reference a valid object. Conversion is handled by the normal syntax:

TSharedPtr<FMyObjectType> MySharedPointer = MySharedReference;

You can create a Shared Reference from a Shared Pointer with the Shared Pointer function, ToSharedRef, as long as the Shared Pointer references a non-null object. Attempting to create a Shared Reference from a null Shared Pointer will cause the program to assert.

// Ensure your shared pointer is valid before dereferencing to avoid a potential assertion.
If (MySharedPointer.IsValid())
{
    MySharedReference = MySharedPointer.ToSharedRef();
}

Comparison

You can test Shared References against each other for equality. In this context, equality means referencing the same object.

TSharedRef<FMyObjectType> ReferenceA, ReferenceB;
if (ReferenceA == ReferenceB)
{
    // ...
}
Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.
Take our survey
Dismiss