Ariba 0.9.x Series

The ariba 0.9.x development branch brings great performance and stability improvements at cost of backward compatibility.

It contains optimizations on the binary level, also some prior design descisions have been reconsidered to provide easier, faster and less error-prone interfaces. Therefore the new ariba 0.9.x series is not compatible with prior ariba version; not in terms of network connectivity, also most applications won't compile without some modifications. The latter is especially due the introduction of a new configuration format (using json or xml) and a cleaner interface to startup ariba in the application. Also bluetooth and the bootstrap modules have not been ported to some new internal interfaces, yet and can't be used at the moment.

Please note that the ariba documentation on this site still refers to the old ariba 0.8.x series. In order to work with the new ariba 0.9.x series, please consider the interface changes presented on this page.

Changelog

A brief list of changes between ariba 0.8.x and 0.9.x:

improvements:

• new message classes (reboost, zero-copy)
• "fast path" for direct links (skip overlay layer)
• link-properties accessible from the application
• System-Queue can call boost::bind functions
• protlib compatibility removed (32bit overhead saved in every message)
• addressing2, (a new interface for ip-/bluetooth addresses)
• Address-Discovery discoveres only addresses on which we're actually listening
• ariba serialization usage reduced (sill used in OverlayMsg)
• Node::connect, easier and cleaner interface to start-up ariba from the application
• ariba configs via JSON, XML, etc (boost::property_tree)
• keep-alive overhead greatly reduced
• (relayed) overlay links can actually be closed now
• lost messages are detected in most cases
• notification to the application when link is transformed into direct-link
• overlay routing: send message to second best hop if it would be dropped otherwise
• Sequence-Numbers (only mechanisms so far: upward compatibility)
• various small fixes

regressions:

• bluetooth is not yet working again
• bootstrap modules deactivated
• liblog4xx is not working (use cout-logging)

Using ariba 0.9.x

To get to code, please check out the latest trunk version from our svn: ​Ariba-SVN

Configuration format

Ariba 0.9.x uses a new configuration format, based in boost::property_tree. Hence you can use the JSON format to store ariba configs. Other formats (e.g. XML) are supported, too. Please refor to the documentation: ​Boost.PropertyTree

Example configuration file

//JSON
{
    "ariba": {
        "node_name": "Node1",
        "spovnet_name": "pingpong",
        
        "listen_on": [
            {"category": "TCPIP", "addr": "::", "port": 5000 }
        ],
        
        "bootstrap": {
            "direct": [
                {"category": "TCPIP", "addr": "127.0.0.1", "port": 41322 }
            ],
        }
    }
}

• As in earlier ariba versions the node_name and the spovnet_name can be specified. Please keep in mind that node names must be unique and all nodes must use the same spovnet name in order to communicate.
• listen_on describes an array of local addresses, on which ariba will listen.
  • Since bluetooth is currently disabled, category must be TCPIP
  • addr can either be an ipv4 or ipv6 address ("::" is the ipv6 any-address)
  • a port can be specified, if port 0 is given, ariba will try to find a usable port (starting with port 41322)
• bootstrap defines the bootstrap hints, the nodes ariba tries to connect in order to join the spovnet
  • Since the bootstrap modules are currently disabled, only direct bootstrapping is available
  • direct describes an array of remote endpoints ariba tries to connect to (same syntax as the listen_on field)

Note that all ariba related config is stored in a field named ariba. The same JSON file can be used to store application specific config data as well.

Ping-pong example

The ping-pong code in the SVN trunk differs from the detailed explanation in the wiki. Especially the new config format (see above) and Node::connect, the new easy and clean interface to start-up ariba (see below) is used.

Please note that the ping-pong example still uses the old deprecated ariba messages (see next section "Message formats" for more information).

void PingPong::startup()
{
    using boost::property_tree::ptree;
    using boost::property_tree::json_parser::read_json;
    
    logging_info( "[PINGPONG]\t starting up PingPong service ... " );

    // read config
    ptree config;
    try
    {
        read_json(config_file, config);
    }
    catch ( exception& e )
    {
        logging_warn("ERROR: Failed to read config file »" << config_file << "«: ");
        logging_warn(e.what());
        logging_warn("---> Using fallback config.");
        
        config.put("ariba.spovnet_name", "pingpong");
    }
    
    // use node name also in the application
    name = config.get("ariba.node_name", "NO_NAME");
    
    // bind communication and node listener
    node.bind( this );                              /*NodeListener*/
    node.bind( this, PingPong::PINGPONG_SERVICEID); /*CommunicationListener*/

    // connecting
    logging_debug( "connecting ... " );

    node.connect(config.get_child("ariba"));

    // ping pong started up...
    logging_info( "[PINGPONG]\t pingpong starting up with"
                        << " [spovnetid " << node.getSpoVNetId().toString() << "]"
                        << " and [nodeid " << node.getNodeId().toString() << "]" );
}

• ptree config; is an yet empty instance of boost::property_tree::ptree.
• read_json(config_file, config); reads a config file (like the JSON file showed in the previous section) into the ptree instance config. The path of the JSON file is stored in config_file.
  • If the read fails, the except handler prints a warning and initiates a default config directly within the code via: config.put("ariba.spovnet_name", "pingpong");
• The node variable is defined as attribute: ariba::Node node; (initialized with the standard constructor). Thoe follwing registers the callbacks from ariba:
  • node.bind( this );
  • node.bind( this, PingPong::PINGPONG_SERVICEID);
• The following command starts ariba with the config stored in the ptree
  • node.connect(config.get_child("ariba"));

Interfaces

• The callbacks (functions in the application that are called from ariba) are declared in:
  • ariba/CommunicationListener.h.
• The ariba interface (functions in ariba that can be called from the application) are declared in:
  • ariba/Node.h.

Message formats

The ping pong example still uses the old deprecated ariba::message messages with the ariba built-in serialization. For future applications please use the new reboost::message_t messages. Data is stored in high efficient zero-copy buffers of type reboost::shared_buffer_t. These buffers hold plain data, so you have to serialize the data "on your own".

We recommend third-party serialization libraries like:

• Protocol Buffers (​http://en.wikipedia.org/wiki/Protocol_Buffers)
• Message Pack (​http://en.wikipedia.org/wiki/MessagePack)

reboost::message_t