| AngelScript |

Weak references

Even though AngelScript uses a garbage collector to resolve cyclic references weak references may still come in handy. Weak references are especifically useful in scenarios were an object wants to be able to access other objects, but do not want to kept them alive longer than necessary.

AngelScript supports weak references with the use of shared booleans. The code that wants to keep a weak reference to an object should obtain the weakref flag from that object, which is a shared boolean, and before using the pointer to the object it should check if this flag has been set to indicate that the object is no longer alive.

Script classes automatically supports weak references without the script writing having to do anything. Application registered types on the other hand must register the behaviour asBEHAVE_GET_WEAKREF_FLAG and implement the logic to set the flag upon destroying the object.

The following code shows how to do a thread safe implementation:

class MyClass
{
public:
MyClass() { refCount = 1; weakRefFlag = 0; }
void AddRef() { asAtomicInc(refCount); }
void Release()
{
// If the weak ref flag exists it is because someone held a weak ref
// and that someone may add a reference to the object at any time. It
// is ok to check the existance of the weakRefFlag without locking here
// because if the refCount is 1 then no other thread is currently
// creating the weakRefFlag.
if( refCount == 1 && weakRefFlag )
{
// Set the flag to tell others that the object is no longer alive
// We must do this before decreasing the refCount to 0 so we don't
// end up with a race condition between this thread attempting to
// destroy the object and the other that temporary added a strong
// ref from the weak ref.
weakRefFlag->Set(true);
}
if( asAtomicDec(refCount) == 0 )
delete this;
}
asILockableSharedBool *GetWeakRefFlag()
{
if( !weakRefFlag )
{
// Lock globally so no other thread can attempt
// to create a shared bool at the same time
asAcquireExclusiveLock();
// Make sure another thread didn't create the
// flag while we waited for the lock
if( !weakRefFlag )
weakRefFlag = asCreateLockableSharedBool();
asReleaseExclusiveLock();
}
return weakRefFlag;
}
static MyClass *Factory() { return new MyClass(); }
protected:
~MyClass()
{
// Release the weak reference flag that may still
// be accessed by the code that holds a weak reference
if( weakRefFlag )
weakRefFlag->Release();
}
int refCount;
asILockableSharedBool *weakRefFlag;
};

The asBEHAVE_GET_WEAKREF_FLAG behaviour for this class is registered like this:

engine->RegisterObjectType("MyClass", 0, asOBJ_REF);
engine->RegisterObjectBehaviour("MyClass", asBEHAVE_ADDREF, "void f()", asMETHOD(MyClass, AddRef), asCALL_THISCALL);
engine->RegisterObjectBehaviour("MyClass", asBEHAVE_RELEASE, "void f()", asMETHOD(MyClass, Release), asCALL_THISCALL);
engine->RegisterObjectBehaviour("MyClass", asBEHAVE_GET_WEAKREF_FLAG, "int &f()", asMETHOD(MyClass, GetWeakRefFlag), asCALL_THISCALL);

The script language doesn't have a built-in syntax for weak references. Instead a standard weakref add-on has been implemented to provide this for the applications that wants to provide this support in the scripts.

asBEHAVE_RELEASE
@ asBEHAVE_RELEASE
Release.
Definition: angelscript.h:372
asIScriptEngine::RegisterObjectType
virtual int RegisterObjectType(const char *obj, int byteSize, asDWORD flags)=0
Registers a new object type.
asOBJ_REF
@ asOBJ_REF
A reference type.
Definition: angelscript.h:254
asIScriptEngine::RegisterObjectBehaviour
virtual int RegisterObjectBehaviour(const char *obj, asEBehaviours behaviour, const char *declaration, const asSFuncPtr &funcPointer, asDWORD callConv, void *auxiliary=0, int compositeOffset=0, bool isCompositeIndirect=false)=0
Registers a behaviour for the object type.
asAtomicInc
AS_API int asAtomicInc(int &value)
Increments the value by one and returns the result as a single atomic instruction.
asAcquireExclusiveLock
AS_API void asAcquireExclusiveLock()
Acquire an exclusive lock.
asBEHAVE_GET_WEAKREF_FLAG
@ asBEHAVE_GET_WEAKREF_FLAG
Obtain weak ref flag.
Definition: angelscript.h:374
asMETHOD
#define asMETHOD(c, m)
Returns an asSFuncPtr representing the class method specified by class and method name.
Definition: angelscript.h:750
asReleaseExclusiveLock
AS_API void asReleaseExclusiveLock()
Release an exclusive lock.
asAtomicDec
AS_API int asAtomicDec(int &value)
Decrements the value by one and returns the result as a single atomic instruction.
asCALL_THISCALL
@ asCALL_THISCALL
A thiscall class method.
Definition: angelscript.h:236
asILockableSharedBool
A lockable shared boolean.
Definition: angelscript.h:4250
asCreateLockableSharedBool
AS_API asILockableSharedBool * asCreateLockableSharedBool()
Create a lockable shared boolean.
asBEHAVE_ADDREF
@ asBEHAVE_ADDREF
AddRef.
Definition: angelscript.h:370