Ok, I think I've figured out the reason why Mogre returns null references at arbitrary non-deterministic moments during multi-threaded memory heavy applications.
The remainder of this topic is for whoever understands the Mogre architecture. I'll basically walk you through the steps performed during the creation of a simple SceneNode and explain you why the currently implemented behavior results in a race condition leading to null references.
Lastly, I'll propose a solution, and we can then sit down and discuss the pros and cons of it. But rest assured, this is a F**** time-bomb waiting to happen. This bug needs to be squashed now for the good of Mogre's future.
Let us begin the voyage:
1. The managed code
node = sceneMgr.CreateSceneNode();
A simple directive at first, but let us step on how Mogre actually handles this:
2. The unmanaged surface
Mogre::SceneNode^ SceneManager::CreateSceneNode( )
{
return static_cast<Ogre::SceneManager*>(_native)->createSceneNode( );
}
A single line of code, but hiding so many mysteries. We are basically calling the createSceneNode() function from the NATIVE sceneManager instance and returning its result. However, notice that createSceneNode() originally returns Ogre::SceneNode* and NOT Mogre::SceneNode^. So how does the magic happen?
Basically, there are a set of implicit operators converting to and from managed and native types, defined in a ready-made MACRO expansion (debugging nightmare). Here they are:
3. The Macro Expansion nightmare
#define DEFINE_MANAGED_NATIVE_CONVERSIONS(T) \
static operator T^ (const Ogre::T* t) { \
RETURN_CLR_OBJECT(T, (const_cast<Ogre::T*>(t)) ) \
} \
static operator T^ (const Ogre::T& t) { \
RETURN_CLR_OBJECT(T, (&const_cast<Ogre::T&>(t)) ) \
} \
inline static operator Ogre::T* (T^ t) { \
return (t == CLR_NULL) ? 0 : static_cast<Ogre::T*>(t->_native); \
} \
inline static operator Ogre::T& (T^ t) { \
return *static_cast<Ogre::T*>(t->_native); \
}
These macros are defined for all MOGRE classes, and as such, for the Mogre::SceneNode class. From this whole set, we're basically interested in the first function:
static operator T^ (const Ogre::T* t) {
RETURN_CLR_OBJECT(T, (const_cast<Ogre::T*>(t)) )
}
The conversion function is itself implemented by yet another Macro expansion, defined as:
#define RETURN_CLR_OBJECT(T,n) \
if (n == 0) return nullptr; \
Object^ clr = *n; \
if (nullptr == clr) { \
n->_Init_CLRObject(); \
clr = *n; \
} \
return static_cast<T^>(clr);
Starting to get scared? Well, you should be, for this is exactly where the race condition responsible for the bug happens. Let's recap the execution up to this point to see where we stand.
The low-level createSceneNode() was called and the result passed on to the implicit conversion operator, and then to the above macro. The parameter 'n' of the macro now holds the Ogre::SceneNode* pointer.
Continuing:
if (n == 0) return nullptr;
The parameter 'n' is not zero, so this condition is cleared, leading us to:
Object^ clr = *n;
Yet another black magic happens. The Ogre::SceneNode* pointer is converted to a System::Object^ managed reference. As expected, this is done by another implicit conversion, but this time of a different nature.
4. The parallel inheritance hierarchies
As it stands, Mogre does its wrapping magic by defining two parallel hierarchies closely intertwined. On the one hand, there is the original Ogre unmanaged class hierarchy, with the twist that all classes inherit from a special top level class, the CLRObject.
On the other hand, there is Mogre's own class hierarchy, mirroring that of Ogre, but with all classes deriving from another special class, aptly named Wrapper.
So, how do these two interrelate? Let us step in the CLRObject class, to see a special implicit conversion operator:
inline operator Object^ () {
if (_handle == 0)
return nullptr;
else
return __VOIDPTR_TO_GCHANDLE(_handle).Target;
}
Returning to the line currently under analysis, we are now in a position to understand it:
Object^ clr = *n;
The parameter 'n' is of type Ogre::SceneNode* which in turn inherits from CLRObject, inheriting this implicit conversion operator to Object^. Basically, each CLRObject holds an internal reference, implemented via GCHandle instances, to managed objects.
When this conversion operator is called to, it basically uses this reference to access the managed reference and returns it. Of course, if the reference is 0, it has no choice but to return a null reference.
CLRObjects have their handles initialized to 0 in the default constructor, so the Ogre::SceneNode* instance gets converted to a null reference. The next macro lines show us how CLRObjects come to possess non-null references:
if (nullptr == clr) { \
n->_Init_CLRObject(); \
clr = *n; \
}
So basically if the CLRObject is yet to be initialized, Mogre initializes them, via the _Init_CLRObject() virtual method. What this method does is basically instantiate a new MOGRE class FROM the UNMANAGED side, via these Macro expansions:
//for subclasses of CLRObject
#define DECLARE_INIT_CLROBJECT_METHOD_OVERRIDE(T) virtual void _Init_CLRObject(void) { _Init_CLRObject_##T(this); }
and (for each derived class)
#define DEFINE_INIT_METHOD(T) \
void _Init_CLRObject_##T(CLRObject* pClrObj) \
{ \
*pClrObj = gcnew Mogre::T(pClrObj); \
}
If you're somehow still following me, hang strong, for we are getting very close to the hot spot.
So basically, Mogre calls these _Init_CLRObject_##T methods using instances of CLRObject and the 'pClrObj' parameter is the very pointer to the native CLRObject used to make the call. Confusing?
Following our example should make it clear. Basically, the Ogre::SceneNode* pointer is passed inside this function, where the constructor for the MANAGED counterpart to the class is called. In this case, the Mogre::SceneNode constructor is called.
And then, yet another black magic. This managed reference is assigned to the unmanaged instance passed to the function. How is this possible? The CLRObject class has another black magic operator to do this, this time an assignment operator:
inline CLRObject& operator=(Object^ t) {
if (_handle == 0)
_handle = __GCHANDLE_TO_VOIDPTR(GCHandle::Alloc(t, GCHandleType::Weak));
else
__VOIDPTR_TO_GCHANDLE(_handle).Target = t;
return *this;
}
What this does is create a GCHandle to the managed reference. A GCHandle is a special struct of .NET allowing unmanaged code to keep a reference to managed classes. By creating a GCHandle we can get a pointer which can be used to refetch the instance at some point later in time.
This is where the race-condition manifests. GCHandle has several modes of operation (Pinned, Normal, Weak and WeakTrackResurrection).
Pinned means that the garbage collector can't move the memory pointed to by the managed object.
Normal means that the garbage collector can't destroy the managed object until the GCHandle is freed.
Mogre uses Weak, so what does it mean? It basically means that the GCHandle reference doesn't stop the garbage collector from collecting the object. From that point on, accessing the Target property on the GCHandle simply returns null references.
And THAT is the reason why Mogre non-deterministically returns null references. Basically, in the _Init_CLRHandle method, ogre did this:
void _Init_CLRObject_##T(CLRObject* pClrObj) \
{ \
*pClrObj = gcnew Mogre::T(pClrObj); \
}
NO REFERENCE is kept anywhere from this method, and the CLRObject only keeps a WEAK reference to the created object. This means that from this point on, unless someone gets a hold of it, the garbage collector WILL mark this object for collection on the next opportunity.
Let us look again at the final lines of the RETURN_CLR_OBJECT macro:
if (nullptr == clr) { \
n->_Init_CLRObject(); \
clr = *n; \
}
The _Init_CLRObject() creates and immediately lets go of the managed object. The line
clr = *n;
will obtain it again by using the GCHandle reference. But what if something happens BETWEEN these two lines of code? More specifically, what happens if the GC starts functioning in between? Basically, the managed reference will be immediately collected, and from this point on, the GCHandle will only return null.
This CAN happen in any .NET application, since the GC runs on a separate thread. If a garbage collection happens between these two lines, Mogre is helpless and won't ever notice the trouble it's gotten itself into.
If anyone survived through this, my suggestion:
Change the GCHandle::Alloc to use a Normal reference and not a Weak one. We want Ogre classes to manage the .NET classes lifetime anyway, so this is the way it should be.
More specifically, this change SHOULD fix everything if my theory proves right:
inline CLRObject& operator=(Object^ t) {
if (_handle == 0)
_handle = __GCHANDLE_TO_VOIDPTR(GCHandle::Alloc(t, GCHandleType::Weak));
else
__VOIDPTR_TO_GCHANDLE(_handle).Target = t;
return *this;
}
change to
inline CLRObject& operator=(Object^ t) {
if (_handle == 0)
_handle = __GCHANDLE_TO_VOIDPTR(GCHandle::Alloc(t, GCHandleType::Normal));
else
__VOIDPTR_TO_GCHANDLE(_handle).Target = t;
return *this;
}
And it should be fixed. Unless there is some side-effect to changing it to Normal (I checked it and didn't find anything)....
I've tested it on my own error revealing sample (see above) and it has worked for one hour (so far) and with no memory leaks or crashes whatsoever
.
I'm sorry for the HUGE rambling, but I just had to let my findings registered somewhere, and if they have even the smallest chance of inspiring someone to clean-up this architecture, I thought they should be made public.
Best regards,
Gonçalo
project we already have a starting point. The cpp2java tool can make a very easy to read meta.xml file with all the description (namespace, classes,methods,structs and enum) of Ogre (c++) headers we "just" need build a new Autowrapper