A: VOS uses a reference-counted memory management scheme. This means that each reference-counted object (implemented by subclassing "RefCounted" in the C++ library) has a "count" associated with it. This count is the number of times that this object is pointed ("referred") to somewhere in the running program. When a new reference is created (the refcounted object is "acquired") the reference count is incremented. When the a reference is destroyed (the refcounted object is "released") the count is decremented. When the reference count drops to zero, the object can be safely deallocated because we know there are no references to it left in the program.

The purpose of vRef is help you use with VOS's reference counting with a minimum amout of fuss. The vRef template is what is known as a "smart pointer". It is a small class which holds the reference to some object and automatically releases that reference when the vRef class is destroyed. It frees you from most of the hassle of dealing with memory management (at least as far as vobjects and related classes are concerned.) You should always use vRef whenever you get a RefCounted object from VOS.

Keep in mind that vRef automatically releases the object, but it does not acquire an object that you assign to it: if you want to store a reference to an object beyond the scope of its current vRef, acquire it (call acquire()) when you assign the pointer or vRef in which you will be storing it.

You may notice that some code uses certain macros rREF and pREF. These perform a very similar function to the vRef smart pointer (automatically releases a reference when it is no longer accessable), but suffered from a few problems and are now deprecated in favor of vRef. For details about rREF and pREF please consult the API documentation. New code should just use vRef, and old code is slowly being converted.

A: Being polymorphic, Vobjects may implement many different interfaces. The mechanism to select between these interfaces is meta_cast(). This method is intended to appear similar to other C++ typecasting functions (dynamic_cast, reinterpert_cast, static_cast) so it should be comfortable if you are familiar with C++ casts. Using meta_cast is simple: you give it a Vobject and a desired interface class, and you get back a reference or pointer of the appropriate class. If the Vobject does not support the desired class, then it will throw a bad_cast exception (if you did a cast or a reference) or return NULL (if you did a cast on a pointer.) An example:

try {
    vRef<Vobject> myobject = findObject("foo");
    FunkyInterface& fi = MetaObject::meta_cast<FunkyInterface&>(myobject);
    fi.funkyMethod();
} catch(bad_cast) {
    LOG("myprogram", 2, "foo is not a FunkyInterface!");
} catch(Vobject::NoSuchObjectError) {
    LOG("myprogram", 2, "foo does not exist");
}
		  

One important detail is that meta_cast does NOT increment the reference count, so its result doesn't neccesarily need to be stored in a vRef.

This dynamic polymorphism is implemented using the MetaObject extensions discussed earlier. Each interface is usually a different actual C++ object. Behind the scenes these objects are rigged up to seamlessly act as the same logical Vobject. Internally, meta_cast works by going through each metaobject extension attached to the object and performing a C++ dynamic_cast to test for support for the desired interface; the first object which does support the interface is returned to the user.