Cleanup of the network API

Cleanup of the network API

Author: Stefan Eilemann

State: Design

Overview

Replace 32-bit Object identifiers by 128-bit UUID's. Move object registration to net::Node. Remove net::Session.

API

• New type uint128_t

  • Check with system availability (Windows/Linux)
  • If not available, define as struct{ uint64_t high; uint64_t low; }
  • Create operators to convert from/to UUID

• net::Node:

  • Remove:
    • registerSession, deregisterSession, mapSession, unmapSession, getSession, hasSessions
  • See below for new functions from net::Session
  • Refactor local[listening] and remote[connected] node functionality into private impl

• net::Session:

  • Class disappears
  • Remove without replacement:
    • genIDs, freeIDs, setIDMaster, unsetIDMaster, getIDMaster,
  • Move to net::Node:
    • registerObject, deregisterObject, mapObject, unmapObject, attachObject, detachObject, InstanceDataCache

• net::Object:

  • Version will be UUID:
    • Master version are continous, starting at 0:1
    • Slave versions are random and have never 0 as high-order value
    • [new] Master objects can sync to concrete slave commit version
  • Method signature changes from uint32_t -> UUID:
    • getID, commit, commitSync, sync, getHeadVersion, getVersion, getOldestVersion, notifyNewHeadVersion, notifyNewVersion

• eq::Config:

  • subclasses from fabric::Object instead of net::Session
  • ConfigProxy disappears
  • method signature changes from uint32_t -> uint128_t:
    • init, startFrame, find< Object >

• eq::Node, Pipe, Window, Channel:

  • method signature changes from uint32_t -> uint128_t:
    • configInit, all frameFoo task methods

Tasks

Create Collage (eq::net) library

• Move to 'namespace co' and libCollage.so/dylib/dll
• Rename all namespaces accordingly
• Link library from Equalizer
• Use namespace alias to keep eq::net name in Equalizer
• Modify CMake
• Include only necessary eq::base class.

3-5 days

New type uint128_t

• create class uint128_t
• move field and base function from UUID to uint128_t
• UUID is now a subclass from uint128_t
• add Convertion operator =, ++, --, +, etc.
• add unit test in UUID test application
• make all field uint32_t version = UUID version
• make all field uint32_t frameID = uint128_t frameID

2 - 3 day

Separate net::Node implementation

• Use net::Node as a base class / function with recvThread
• Create two private implementation classes: LocalNode and RemoteNode.

1 week

uint128_t object IDs and versions

• Remove ObjectVersion
• change Objects methode signature from uint32_t -> UUID
• Change net::Object, net::Session
• Change eq::Config
• Change node, pipe, window
• Change Channel
• Slave object commit returns version now!

3 - 4 days

Remove ID generation from session

Remove master node lookup hash from session

Remove net::Session

• Move to net::Node: registerObject, deregisterObject, mapObject, unmapObject, attachObject, detachObject, InstanceDataCache.
• fabric::Config subclasses from fabric::Object instead of net::Session
• remove fabric::ConfigProxy

2 - 3 days works

DESIGN

remove NodeIDHash and implement new system NodeID finder

modify Session::MapObject
 - remove NodeIDHash definition and function which serve to find the ID
 - add new system research corresponding to the following algorithm

    Nodes nodes = _local->getNodes()
    for each node in the nodes vector
        send Packet findNode
        wait request
        if nodeID != ZERO
            break;

_cmdFindNodeID( Command& command ) const UUID& id = packet.id; Object* object = _objects.find( id ) if object send reply packet with the NodeID else send reply packet with id ZERO

_cmdReplyFindNode( Command& command ) serveRequest( NodeID )

Issues

1. Do we need to keep compatibility methods for uint32_t client API?

The compatibility methods would wrap/unwrap the 32 bit value from/to an UUID. How to handle unwrap if the 12 high-order bytes are not 0?

eile: imo not needed.

2. Do we need to keep compatibility methods for Config object mapping?

In the new API, Objects are registered with the local net::Node, which is the eq::Client. The compatibility methods in eq::Config would forward the local client.

eile: imo not needed.

3. Who keeps the id->master mapping?

Nobody: The mapping node queries all connected nodes for the master node of the object. This requires the master node to be connected. The client library will connect the application node early in the initialization. Versioned slave objects, which know the master node ID, will be used to accelerate the master node lookup.