AcediaCore/docs/safety.md

Acedia's safety rules

When working with UnrealScript one can distinguish between following types of variables:

1. Value types: bool, byte, int, float, string and any structs;
2. Actors: objects that have Actor as their parent;
3. Non-actor objects: object of any class not derived derived from the Actor.

Most of the mods mainly use first and second type, but we make heavy use of the third one. This allows Acedia to provide convenient interfaces for its functionality and simplify implementation of its features. However it also creates several new problems, normally not encountered by other mods. Here we will introduce and briefly explain three main rules that you need to keep in mind when working with Acedia.

Rule 1: Do not store references to actors in non-actor objects

Storing actors in non-actor objects is a bad idea and can lead to game/server crashes. If you are interested in the explanation of why, you can read discussion here. This isn't really a problem in most mutators, since they store references to actors (KFMonster, KFPlayerController, ...) inside other actors (Mutator, GameType, ...). However, in Acedia almost everything is a non-actor object, so simply having actor variables can be volatile: even a simple check myActor != none can lead to a crash if myActor was destroyed recently enough.

Acedia's end goal is to provide you with enough wrappers, so that you don't have to reference actors directly. We are a long way away from that, so for whenever our API is not enough, we also provide a safer way to work with actors inside objects (see Actor references with NativeActorRef).

Rule 2: Take care to explicitly free unneeded objects

We'll illustrate this point with Text - Acedia's own type that is used as a replacement for string. Consider following simple code:

function MyFunction()
{
    local string message;
    message = "My log message";
    Log(message);
}

For Acedia's Text an equivalent code would be:

function MyFunction()
{
    local Text message;
    message = _.text.FromString("My log message");
    _.logger.Info(message); //  Just Acedia's logging, kind of like `Log()`
}

There is an additional action of calling FromString() to create a new Text object, but otherwise logic is the same. But there's one crucial difference: unlike string value, Text is an object that will continue to exists in memory even after we exit MyFunction()'s body: every single call to MyFunction() will keep creating new objects that won't ever be used anywhere else.

Supposed way to deal with this is garbage collection, but it is a very expensive operation in Unreal Engines before their 3rd version. For example, the lag at the start of each wave in Killing Floor is caused by a garbage collection call. Many players hate it and several mods were made to disable it, since there is usually not much to actually clean up.

This means that Acedia needed to find another way of dealing with issue of creating useless objects. That solution is deallocating objects:

function MyFunction()
{
    local Text message;
    message = _.text.FromString("My log message");
    _.logger.Info(message);
    message.FreeSelf(); //  `_.memory.Free(message)` would also work
}

Here FreeSelf() call marks message as an unneeded object, making it available to be reused. In fact, if you call new MyFunction() several times in a row:

MyFunction()
MyFunction()
//  Paste a couple thousand more calls here
MyFunction()

all of the calls will use only one Text object - the exactly same as the one first call has created.

This concerns not only Text, but almost every single Acedia's object. To efficiently use Acedia, you must learn to deallocate objects that are not going to be used anymore.

Rule 3: You should never ever use anything you've deallocated

IMPORTANT: This is the most important rule - violating will create bugs that are extremely hard to catch. And possibility of such bugs is the biggest downside of using Acedia.

If Text variable from above wasn't local, but global variable, then we'd have to add one more instruction message = none:

var Text message;

function MyFunction()
{
    message = _.text.FromString("My log message");
    _.logger.Info(message);
    message.FreeSelf();
    message = none; // Forget about `message`!
}

Deallocating a message does not make an actual object go away and, without setting message variable to none, you risk continuing to use it; however, some other piece of code might re-allocate that object and use it for something completely different. This means unpredictable and undefined behavior for everybody. To avoid creating with this problem - everyone must always make sure to forget about objects you've deallocated by setting their references to none.

NOTE: This also means that you should not deallocate the same object more than once.