Changes between Initial Version and Version 1 of Documentation/ariba_0_9_x

Timestamp:

Jun 21, 2013, 4:03:10 PM (11 years ago)

Author:

hock@…

Comment:

move wiki/ariba_0_9 to wiki/Documentation/ariba_0_9_x

Documentation/ariba_0_9_x

@@ +1 @@
+== '''Ariba 0.9.x Series''' ==
+
+The ariba 0.9.x development branch brings great performance and stability improvements at cost of backward compatibility.
+
+The network traffic was optimized on the binary level, and 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; in terms of network connectivity, and 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 support and the bootstrap modules have not been ported to some new internal interfaces, yet and can't be used at the moment.
+
+Ariba 0.9.x is still under development and is currently in a testing phase. However you can get the code from our svn: [https://i72projekte.tm.uka.de/SpoVNet-KA/entwicklung/ariba/trunk Ariba-SVN]. We appreciate bug reports and feedback.
+
+''Please note that the [https://svn.tm.kit.edu/trac/spovnet-base/wiki/BaseGuide ariba documentation] still refers to the old ariba 0.8.x series. This page presents the new interfaces and changes of ariba 0.9.x.''
+
+=== ''' 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 (still used in Overlay-Msg)
+    - 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: [https://i72projekte.tm.uka.de/SpoVNet-KA/entwicklung/ariba/trunk 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: [http://www.boost.org/doc/libs/1_46_1/doc/html/property_tree.html 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).
+
+{{{
+#!cpp
+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 '''
+
+The reboost::message_t is an Copy-on-Write Message with Shared Buffers.
+
+A message holds a limited (defined by `message_max_buffers`, typically `8`) number of shared buffers. One can add new buffers and messages in front and at the end of a message. If the no. of buffers exceed `message_max_buffers`, then the two smallest successive buffers are compacted to one buffer.
+
+Typical operations:
+  - reboost::message_t msg;
+    - creates an empty message
+  - void message_t::push_back(shared_buffer_t)
+  - void message_t::push_front(shared_buffer_t)
+  - shared_buffer_t message_t::linearize()
+  - size_t message_t::size()
+
+For more information refer to the source code: `ariba/utility/transport/messages/message.hpp`
+
+''' reboost::shared_buffer_t '''
+
+A simple shared buffer.
+
+Important: if not shared, a buffer is writable. After the buffer is shared, the buffer is immutable. It uses shared_ptr/default allocators and prints error messages to `cerr` if buffers leaked at the end of the program (only in `debug` mode).
+
+Typical operations:
+
+  - shared_buffer_t(size_t size)
+    - creates a shared buffer of a specific size
+    - allocates memory and frees after destruction
+  - shared_buffer_t(unsigned char* buffer, size_t size)
+    - creates a shared buffer from existing data
+    - transfers ownership
+    - frees memory after destruction
+  - shared_buffer_t shared_buffer_t::operator()(size_t index, size_t size = 0)
+    - return sub-buffer
+    - example: `shared_buffer_t sub_buff = buff(15)`;
+  - const uint8_t* data = buff.data();
+    - access data as array (read-only)
+  - uint8_t* data = buff.mutable_data();
+    - access data as array (writable)
+    - NOTE: only if buffer is not shared, yet
+
+For more information refer to the source code: `ariba/utility/transport/messages/shared_buffer.hpp`
+
+
+=== ''' System Queue ''' ===
+
+Instead of implementing `ariba::utility::SystemEventListener` and multiplex different events in the `handleSystemEvent` callback, it's now possible to schedule a function call into the System Queue, using boost::bind.
+
+This may look like this:
+
+{{{
+#!cpp
+void MyClass::some_function()
+{
+    string param1 = "hello";
+    int param2 = 5;
+
+    // schedule call of "myfunction(param1, param2)" into System Queue
+    SystemQueue::instance().scheduleCall(
+            boost::bind(
+                    &MyClass::myfunction,
+                    this,
+                    param1,
+                    param2)
+        );
+}
+
+void MyClass::myfunction(string param1, int param2)
+{
+    // do something
+}
+}}}
+
+Also `SystemQueue::scheduleCall` takes an optional second parameter `uint32_t delay`, to schedule a callback the given amount of milli-seconds in the future.