Arma Reforger:Scripting: Automatic Reference Counting

Automatic Reference Counting, shortened to ARC, is a memory management solution used in Enforce Script. Enforce Script does not use Garbage Collection (a.k.a GC). In comparison with the widely used Tracing garbage collection (in e.g C#, Java):

• it does not suffer from cleanup stuttering (lags due to high GC load)
• memory management performance is not dependent on the number of managed instances
• it is simple to implement (having a good working GC is a big issue)

on the negative side, it is open to the cyclic reference problem, described in the Cyclic Reference paragraph below.

ⓘ

This whole system impacts objects passed by reference - see Types.

Principle

Enfusion has an internal counter of strong references to objects; when this counter reaches 0, the object is released from memory.

Strong Reference

A strong reference is a reference to an object that increments the reference counter. The referenced object cannot become null during the program's lifetime unless manually deleted (with the delete keyword).

Strong references:

• using the ref keyword
• scope lifetime's script reference

Weak Reference

A weak reference is a reference to an object that does not increment the reference counter. The reference may become null during the program's lifetime.

Usage

class ExampleClass { // weak reference to an object ReferencedClass m_WeakRefObject; // strong reference to an object ref ReferencedClass m_StrongRefObject; // strong reference to a dynamic array (that is an object itself) of weak references ref array<ReferencedClass> m_aWeakRefArray; // strong reference to dynamic array of strong references ref array<ref ReferencedClass> m_aStrongRefArray; // static array of strong references ref ReferencedClass m_aStrongRefStaticArray[10]; // maps and sets work the same ref map<string, ReferencedClass> m_mWeakRefMap; ref map<string, ref ReferencedClass> m_mStrongRefMap; ref set<ReferencedClass> m_sWeakRefSet; ref set<ref ReferencedClass> m_sStrongRefSet; void Method() { ReferencedClass localReference = new ReferencedClass(); localReference = new ReferencedClass(); // the previous object loses its strong reference and is immediately released // the newly created object replaces it array<ReferencedClass> arrayOfWeakRef = new array<ReferencedClass>(); // array of weak references is created arrayOfWeakRef.Insert(new ReferencedClass()); // ReferencedClass object is created and immediately deleted, as arrayOfWeakRef does not increment the reference counter array<ref ReferencedClass> arrayOfStrongRef = new array<ref ReferencedClass>(); // array of strong references is created arrayOfStrongRef.Insert(new ReferencedClass()); // ReferencedClass object is created and kept // at the end of the method, local variables 'localReference', 'arrayOfWeakRef' and 'arrayOfStrongRef' are released: // localReference is destroyed // arrayOfWeakRef is destroyed (it only contains NULL), // arrayOfStrongRef is destroyed (it contains the last strong ref to object, so its contained object is destroyed as well }; };

Cyclic Reference

Problem

The main issue with reference counting is cyclic references (aka "Island of isolation"). In the code below:

• the main method creates object A and object B
• object A references object B
• object B references object A
• the main method ends, dropping its references to object A and B
• both objects a and b should be deleted but they still reference each other, keeping the reference counting above 0:
  • any reference to them is lost after main method's ending
  • they remain in memory until the program is stopped

class Parent { ref Child m_child; }; class Child { ref Parent m_parent; }; void main() { Parent a = new Parent(); // 'a' has 1 reference Child b = new Child(); // 'b' has 1 reference a.m_child = b; // 'b' has 2 references b.m_parent = a; // 'a' has 2 references // local variables 'a', 'b' are released (reference count is decreased by 1) // both objects remain in memory, having 1 reference each (each other) };

Solution

The solution to this issue is to have one object have a strong reference, while the other only holds a weak one:

class Parent { ref Child m_child; }; class Child { Parent m_parent; }; void main() { Parent a = new Parent(); // 'a' has 1 strong (scope) reference Child b = new Child(); // 'b' has 1 strong (scope) reference a.m_child = b; // 'b' has 2 strong references b.m_parent = a; // 'a' has 1 strong reference, 1 weak reference // local variables 'a', 'b' are released (reference count is decreased by 1) // a only has 1 weak reference and is released from memory // b loses a's reference and has no more reference to it - it gets released };

Using weak references makes null-checking take more importance in scripting.