#define S_DOCUMENTATION
#define S_DOCUMENTATION_DEVELOPER
#define PAGE Documentation
#define SUBPAGE Developer
#define TITLE Distributed Objects

#include "header.shtml"

<p>
  Author: <a href="mailto:eilemann@gmail.com">eilemann@gmail.com</a><br/>
  State:
  <ul>
    <li>Implemented in 0.3 alpha</li>
    <li>Serialization using streams implemented in 0.4</li>
    <li>getChangeType introduced in 0.5</li>
  </ul>
</p>

<p>
  Equalizer provides facilities to ease the data distribution of an
  application. The central piece is the <code>eq::net::Object</code> base class,
  from which distributed objects are derived. Objects become accessable by
  making them known to a session. The example code shipped with Equalizer
  contains examples of distributed objects.
</p>

<h2>Classification</h2>
<p>
  Equalizer can manage static and versioned objects.
</p><p>
  Static objects can be instanciated on multiple nodes. Upon instanciation,
  the data from the master version is replicated to the 'slave' node. Static
  objects do not retain object data, since this data is assumed to be
  immutable.
</p><p> 
  Versioned objects work like a simplified version control system. One
  master copy of the object creates a new version whenever the application
  calls <code>Object::commit</code>. This version is pushed to all subscribers,
  that is, to all nodes which have mapped the object. The version data is queued
  on the object, and will be applied when the application
  calls <code>Object::sync</code> to synchronize a specific version, or the head
  version.
</p><p>
  A simplified type of versioned objects are objects where the instance data is
  equal to the delta data, i.e., objects which sync their full data on each
  commit.
</p>

<h2>Object Mapping</h2>
<p>
  To make objects distributable, they have to be known by the session. During
  this process the change type of object is determined.
</p><p> 
  The master instance of an object is registered
  using <code>Session::registerObject</code>. Upon registration, a
  session-unique identifier is assigned, which can be used to map slave
  instances using <code>Session::mapObject</code>. Mapped slave instance are
  instanciated with the oldest known version from the master instance, and can
  be synchronized to the head version using <code>Object::sync</code>.
</p><p>
  Additionally, the object identifier can be used to send
  an <code>ObjectPacket</code> to another node. Each object instance has a
  node-unique instance identifier to address single instances of an object on a
  remote node.
</p>

<h2>Change Handling</h2>
<p>
  During the registration of the master version of a distributed object, the way
  changes are to be handled is determined by
  calling <code>Object::getChangeType</code>. The change type determines the
  memory footprint and the contract for calling the serialization methods. The
  following change types are possible:
</p>
<ul>
  <li><b>STATIC</b> The object is not versioned. The instance data is serialized
    whenever a new slave instance is mapped. No additional data is stored.</li>
  <li><b>INSTANCE</b> The object is versioned, and the instance and delta data
    is identical, that is, only instance data is serialized. Previous instance
    data is saved to be able to map old versions.</li>
  <li><b>DELTA</b> The object is versioned, and the delta data is typically
    smaller than the instance data. Both the delta and instance data are
    serialized and saved to map old versions.</li>
  <li><b>DELTA_UNBUFFERED</b> The object is versioned, and delta data is used to
    update slave instances. No data is stored, and no previous versions can be
    mapped. The instance data is serialized whenever a new slave instance is
    mapped.</li>
</ul>

<h2>Static Objects</h2>
<p>
  The implementation of unversioned objects is straight-forward and requires the
  application to either declare the distributed data using
  <code>Object::setInstanceData</code> or to implement 
  <code>Object::getInstanceData</code>.
</p>

<h2>Versioned Objects</h2>
<p>
  Versioned objects override the method <code>Object::getChangeType</code> to
  indicate how changes are to be handled. They possibly have to implement, in
  addition to unversioned objects, the methods <code>Object::pack</code>
  and <code>Object::unpack</code> to create or apply a diff from the last
  version. Alternatively they can declare the location of the data
  using <code>Object::setDeltaData</code> on both the master and slave
  instances.
</p><p>
  Objects with the same instance and delta data only distribute instance data
  for each new version, and do not have to implement pack and unpack.
</p>

<h2>Serialization</h2>
<p>
  The object serialization and deserialization methods use
  an <code>DataOStream</code> and <code>DataIStream</code>, respectively. These
  streams behave like iostreams, but transfer the data in a binary format. They
  do no type-checking on the data, that is, it is the application's
  responsibility to <strong>match the order and variables during serialization
  and deserialization exactly</strong>. Currently they implement streaming
  operators for basic data types (int, float, etc.), std::strings and
  std::vectors of basic data types.
</p>

<h2>Object Typing</h2>
<p>Design only:</p>
<pre>
  Provide type with objects: 
      virtual uint32_t Object::getTypeID() const { return EQ_ID_INVALID; }
  Session::instantiateObject( const uint32_t objectID ):
      if( !get object type id from master )
          return 0
     Session::createObject( type );
     map object to objectID
     return object
</pre>

<h2>Multi-Buffered Objects</h2>
<p>Design only!</p>
<h3>Requirements</h3>
<pre>
  - each thread has its own version.
  - only one write thread per object across all nodes
  - sync and getVersion are thread-specific, that is, sync synchronizes this
    object to the given version for this thread only, and getVersion return the
    current version for this thread.
</pre>
<h3>API</h3>
<pre>
  class ???
  {
      ObjectHandle getObject( const uint32_t id, const uint32_t version );
      
  };
  // ObjectHandle releases object/version for reuse when it goes out of scope
</pre>

<h2>Implementation</h2>
<p>
  The header file is in 
  <a href="/cgi-bin/viewvc.cgi/trunk/src/lib/net/object.h?view=markup">src/lib/net/object.h</a>.
</p>
<p>
  Each object has a change manager, which depends on the type of the object and
  its master/slave status. Equalizer implements a change manager for static
  objects, versioned objects with delta data and versioned objects with only
  instance data. Externalizing the implementation of change handling allows for
  optimisations in the implementation and the memory usage for storing the
  version data.
</p>

<h2>Open Issues</h2>
<p>
  Document <code>Session::attachObject</code> for unmanaged
  objects. Document object version obsoletion.
</p>

#include "footer.shtml"
<!-- $Id$ -->