Safety

What Is Safety?

Safety in the context of Atomix means multiple things. Mainly we want to ensure Safe operations are being performed. Take the following example:

FAtomix Entity ...;

// Get the component from the entity
// Will not check if the entity is valid
// Will not check if the entity has the component before trying to get it
// Will cause undefined behaviour (e.g. crash) if the component cannot be retrieved
FExampleComponent& Shell->GetRef<FExampleComponent>(Entity);

This will return a reference to the component assigned to the entity matching the specified type. But there are certain things we must consider.

• Does the Entity exist
• Is the Entity valid
• Does the Entity have the component

Given that we are returning a reference to the desired component, which cannot be null or invalid, how do we handle cases where we cannot provide the desired return value.

A more robust implementation of this would be:

FAtomix Entity ...;

// Check that the entity is valid and exists in the registry
if(!Shell->ValidateEntity(Entity)) return;

// Check that the entity has the component we are attempting to get
if(!Shell->HasAllOf<FExampleComponent>(Entity)) return;

// Get the component from the entity
FExampleComponent& Shell->GetRef<FExampleComponent>(Entity);

The last piece of code requires 3 external function calls to provide safe operation. This is a completely acceptable implementation, but it can be optimised.

Atomix provides the developer with the ability to perform safe operations without much of the boilerplate code. You dont even need to change the methods you are using.

To enable Safe operation within scope, all you need to do is the following:

FAtomix Entity ...;

ATOMIX_SAFE_MODE();

// Get the component from the entity (Safe operation)
// Will check if the entity is valid
// Will check if the entity has the component
// If these conditions are not met:
// It will return a default initialized instance of the specified type
FExampleComponent& Shell->GetRef<FExampleComponent>(Entity);

But sometimes you don't require the overhead of a safe operation, maybe in the case of a Registry View.

for(const FAtomix& Entity... )...{

    { // This scope will provide SAFE operation
        ATOMIX_SAFE_MODE();
        
        // Will check if the entity is valid
        // Will check if the entity has the component
        Shell->RemoveComponent<FExampleComponent>(Entity)
    }
    
    // Outside of the scope operations will be considered UNSAFE
    
    // Will NOT check if the entity is valid
    // If the entity already has the component it will cause undefined behaviour (e.g. Crash).
    // We just validated and removed this component from the entity.
    // Hence we can save ourself the overhead of the validity checks
    Shell->EmplaceComponent<FExampleComponent>(Entity, FExampleComponent{"My Other Component"});

}

The actual overhead of doing these checks is very small, but given we are targeting efficient operation we should try and optimise where we can in most cases.

Safe operations are Thread Specific. So declaring a scope as Safe will only affect the local thread from which it was called. Calling safe mode on the game thread will not affect any async tasks or background threads that may also be interacting with the registry.

Opt-In

It seems odd to have Safety as an Opt-In principle, and you're right it is odd. But for good reason.

Performance is typically a primary concern for ECS implementations. Many ECS operations happen in tight loops where safety checks could significantly impact performance so we should aim to have valid data before we enter into any registry operations.