apps/tutorials/vostut2.cc

Go to the documentation of this file.

/* Second VOS tutorial.  Introduction to Vobjects.

   This tutorial covers:
   - Creating a Vobject on a site
   - Reference counting in VOS
   - Simple Vobjects methods

   This file (vostut2.cc) is released into the public domain.  No
   restrictions are placed on its use, distribution or inclusion into
   other works.
*/

#include <vos/corelibs/vos/vos.hh>

int main(int argc, char** argv)
{
    cout << "VOS Tutorial 2\n\n";

    LocalSocketSite localsite(&NoAccessControl::static_);

    /* The fundamental abstraction in VOS is the "Vobject" (pronounced
       Vee-Object).  A Vobject is an entity which can exchange
       messages with other Vobjects.  Every Vobject is associated with
       a site, and the site provides the means by which the Vobject
       may communicate over a network using standards such as TCP/IP
       sockets.  A Vobject is created using by using the
       createMetaObject() method on a site and assigning the returned
       object to a vRef<> template (explained below). */

    vRef<Vobject> primus = localsite.createMetaObject("primus", 0);

    /* -- Sidebar on Reference Counting --

       Memory management in VOS uses a technique known as Reference
       Counting.  The idea is simple: an object stores the number of
       times it refered to (via a C++ pointer or reference, the two
       are essentially interchangeable) in other parts of the program.
       When an object is constructed, its reference is initially 1.
       As additional pointers to the object are created, the reference
       count is increased, and as those pointers go away the count in
       decreased.  When the count reaches 0, this means the object is
       no longer refered to anywhere in the program and can be safely
       deleted without leaving any dangling pointers.

       When a pointer to an object is returned from a method in VOS,
       the object will usually have had its reference count increased
       (check the API documentation if you are not sure).  If this is
       the case, you must decrease the reference count when you are
       done.  This is done by calling the release() method.  To
       increase the reference count (such as when you are creating a
       new pointer to the object) use the acquire() method.

       To simplify reference counting you can use the smart pointer
       class vRef<>.  It is a template class whose purpose is simply
       to ensure that a reference which you have acquired is released
       when you are done with it.  The way it works is very simple:
       the template holds a pointer to the object.  When the vRef
       object is destroyed (usually by going out of scope) it calles
       release() on the pointer it holds.  Please note a vRef does NOT
       increment the reference count when it is created.  You can,
       however, assign one vRef to another, in which case the count of
       the referenced object WILL be incremented.

       -- End Sidebar on Reference Counting --
     */

    /* Now, back to our VOS tutorial.  Let's look at a few
       simple methods you can use on Vobjects. */

    // Get the Vobject's site name.  This is the name it was created
    // with, and is unique on its site.
    cout << "Vobject site name is: " << primus->getName() << "\n";

    // Get the URL you can use to refer to this Vobject.  It should
    // consist of the hostname of your site and the vobject's unique
    // name.
    cout << "Vobject URL is: " << primus->getURL().getString() << "\n";

    // Get the site the Vobject is associated with, which is our
    // localsite object.  Sites are a subclass Vobjects, so you can
    // use the entire Vobject API (described in this and following
    // tutorials) with sites.
    vRef<Site> site = primus->getSite();
    cout << "Vobject site is: " << site->getURL().getString() << "\n";
    cout << "Our local site is: " << localsite.getURL().getString() << "\n";

    /* Now if you access this site with a VOS browser such as
       "mesh" you will see a single vobject named "primus".  */

    while(true) {
        localsite.flushIncomingBuffers();
    }
}

---