Memory Management
There are a few different memory management systems in UE4: garbage collection, smart pointers, and standard C++ memory management. Garbage Collection Garbage collection (GC) tracks UObject sub-cla...
There are a few different memory management systems in UE4: garbage collection, smart pointers, and standard C++ memory management.
Garbage Collection
Garbage collection (GC) tracks
UObject
sub-classes, which include
[https://docs.unrealengine.com/en-US/API/Runtime/Engine/GameFramework/AActor/index.html AActor]
and
[https://docs.unrealengine.com/en-US/API/Runtime/Engine/Components/UActorComponent/index.html UActorComponent]
.
Objects are primarily kept alive in 3 ways:
- By having a strong reference (
) to them (from objects that are also referenced)[https://docs.unrealengine.com/en-US/Programming/UnrealArchitecture/Reference/Properties/index.html UPROPERTY]
- By adding them to the list of
(from objects that are also referenced)void UObject::AddReferencedObjects(UObject* This, FReferenceCollector& Collector)
- By adding them to the root set with
(typically unnecessary)[https://docs.unrealengine.com/en-US/API/Runtime/CoreUObject/UObject/UObjectBaseUtility/AddToRoot/index.html UObject::AddToRoot]
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).
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
AActor
and
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
FinishDestroy
.
The GC runs in the game thread so it won't ever run as your are accessing an object from the game thread.
While the most common way of keeping alive objects is through a
[https://docs.unrealengine.com/en-US/Programming/UnrealArchitecture/Reference/Properties/index.html 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[1]:
- A raw pointer declared with
(it will be set as nullptr)[https://docs.unrealengine.com/en-US/Programming/UnrealArchitecture/Reference/Properties/index.html UPROPERTY]
- In a
compatible container, such asUObject
,TArray
, orTSet
, if declared withTMap
(the affected element will be set as nullptr but not removed)[https://docs.unrealengine.com/en-US/Programming/UnrealArchitecture/Reference/Properties/index.html UPROPERTY]
- In a
(the reference isn't exactly cleared in this case but callingTWeakObjectPtr
will now return nullptr)Get
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
[https://docs.unrealengine.com/en-US/Programming/UnrealArchitecture/Reference/Properties/index.html 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 function that automatically checks if an object pointer is non-null and not pending kill.
UObjectBase::IsValidLowLevel
and
UObjectBase::IsValidLowLevelFast
are not related to the GC and should not be used for that purpose.
If you write your own non-garbage classes that references garbage collected objects, you may want to sub-class
[https://docs.unrealengine.com/en-US/API/Runtime/CoreUObject/UObject/FGCObject/index.html FCObject]
.
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[2].
Further reading
Documentation
- 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
Other