There are a few different memory management systems in UE4: garbage collection, smart pointers, and standard C++ memory management.
Garbage collection (GC) tracks
UObject sub-classes, which include
UActorComponent. When creating a new
UObject, UE4 will automatically add them to its internal objects list, so even with improper use, it's not easy to have memory leaks, but it is easy to cause crashes. UObjects should never be created with
new, but only with their default creation methods (
Objects are primarily kept alive in 3 ways:
- By having a strong reference (
UPROPERTY) to them (from objects or structs that are also referenced)
- By adding them to the list of
void UObject::AddReferencedObjects(UObject* This, FReferenceCollector& Collector)(from objects or structs that are also referenced)
- By adding them to the root set with
When objects do not fulfill any of the above conditions, on the next GC cycle they will be marked as unreachable and garbage collected (destroyed).
Having an object as an Outer of another object does not automatically mean it will be kept alive. The same goes for default subobjects.
To force the destruction of objects that are still reachable, you can call
MarkPendingKill on them, and it will force their destruction on the next GC cycle (you generally want to avoid doing this as that is what the garbage collection is for, and some classes, like
UActorComponent do not support it).
The destruction of an object doesn't necessarily all happen in the same frame, when garbage collection starts on it, it will first call
BeginDestroy (do not call this yourself), then, when ready
The GC runs in the game thread so it won't ever run as you are accessing an object from the game thread.
While the most common way of keeping alive objects is through a
UPROPERTY, actors and components work differently:
levels reference their actors and actors reference their components. Both work by overriding the
void UObject::AddReferencedObjects(UObject* This, FReferenceCollector& Collector) implementation and collecting what they do not want to be garbage collected. This means that even if there are no strong references to actors and components with an owner, they won't be garbage collected until manually destroyed, or their level is unloaded.
The garbage collector will clear references to garbage collected objects in any of these cases:
- A raw pointer declared with
UPROPERTY(it will be set as nullptr)
- In a
UObjectcompatible container, such as
TMap, if declared with
UPROPERTY(the affected elements will be set as nullptr but not removed)
- In a
TWeakObjectPtr(the reference isn't exactly cleared in this case but calling
Getwill now return nullptr)
Anytime code references an
AActor or a
UActorComponent, it has to deal with the possibility that
AActor::Destroy is called on the actor or
UActorComponent::DestroyComponent is called on the component. These functions will mark them for pending kill, thus triggering their garbage collection at the first chance it gets (note that destroying an actor also destroys all its component). Since the garbage collector automatically nulls out
UPROPERTY pointers when it actually gets to destroy them, null-checking an actor or component pointer is sufficient to know it's safe to use, though you might also want to check
IsPendingKill on them to avoid accessing them after they have been marked for destruction (
TWeakObjectPtr already checks for this when retrieving the raw pointer).
bool IsValid(const UObject* Test) is a global function that automatically checks if an object pointer is non-null and not pending kill.
UObjectBase::IsValidLowLevelFast should not be used for GC checks, as on
UPROPERTY pointers it will always return true, while on raw pointer it will return true or false depending whether the object had already been destroyed, but in the latter case it's also likely to crash the application as the pointed memory could have been overwritten.
If you write your own non-garbage classes that references garbage collected objects, you may want to sub-class
Garbage Collection Performance
The GC will run every x seconds, though it's possible to force its execution at any time. Given that for technical reasons the GC needs to go through every UObject in the same pass (it can't split reference counting over multiple frames), the bigger is the number of UObjects and the more UPROPERTY pointers these objects have, the slower the GC pass will be. The time taken by a pass will also be determined by the amount of objects it needs to destroy.
Unreal Smart Pointer Library
The Unreal Smart Pointer Library is for code that is not based on the UObject system. It is similar in function to the C++11 standard library smart pointers. Unreal Smart Pointers cannot be used to reference UObjects, because the garbage collector isn't aware of smart pointers.
- Objects - Explanations of the basic gameplay elements, Actors and Objects
- Unreal Object Handling - Overview of the features of the UObject system
- Unreal Smart Pointer Library - UE4 implementation of smart pointers, including weak pointers and non-nullable shared references
Related Legacy articles
- Preventing stale actor pointers from crashing your game.
- Garbage collection and dynamic memory allocation.
- Memory Management Example
- UE4 garbage collection overview by Sion Sheevok as part of the Unreal Slackers Discord.