Autobahn|Cpp

Autobahn|Cpp is a subproject of Autobahn which implements the Web Application Messaging Protocol (WAMP) in C++ supporting the following application roles

• Caller
• Callee
• Publisher
• Subscriber

The API and implementation make use of modern C++ 11 and new asynchronous idioms using (upcoming) features of the standard C++ library, in particular Futures, Continuations and Lambdas.

Continuations are one way of managing control flow in an asynchronous program. Other styles include: asynchronous Callbacks, Coroutines (yield or await), Actors (Erlang/OTP, Scala/Akka or Rust) and Transactional memory.

Autobahn|Cpp supports running WAMP (rawsocket-msgpack) over TCP(-TLS), Unix domain sockets or pipes (stdio). The library is "header-only", light-weight (< 2k code lines) and depends on the following:

• C++11 compiler
• boost::future
• boost::asio
• msgpack-c

For getting help, questions or feedback, get in touch on the mailing list, Twitter or IRC #autobahn (Freenode).

Show me some code!

Here is how programming with C++ and Autobahn|Cpp looks like.

Calling a remote Procedure

auto c1 = session.call("com.mathservice.add2", std::make_tuple(23, 777))
    .then([&](boost::future<wamp_call_result> result) {
        std::cout << "Got call result " << result.get().argument<uint64_t>(0) << std::endl;
    });

Registering a remoted Procedure

auto r1 = session.provide("com.myapp.cpp.square",
    [](autobahn::wamp_invocation invocation) {
        std::cout << "Procedure is invoked .." << endl;
        uint64_t x = invocation->argument<uint64_t>(0);
        return x * x;
    })
    .then([](boost::future<autobahn::wamp_registration> reg) {
        std::cout << "Registered with ID " << reg.get().id() << std::endl;
    });

Publishing an Event

session.publish("com.myapp.topic2", std::make_tuple(23, true, std::string("hello")));

Publishing an Event (acknowledged)

auto opts = PublishOptions();
opts.acknowledge = True;

session.publish("com.myapp.topic2", std::make_tuple(23, true, std::string("hello")), opts)
    .then([](boost::future<autobahn::wamp_publication> pub) {
        std::cout << "Published with ID " << pub.get().id() << std::endl;
    });

Subscribing to a Topic

auto s1 = session.subscribe("com.myapp.topic1",
    [](const autobahn::wamp_event& event) {
        std::cout << "Got event: " << event.argument<uint64_t>(0) << std::endl;
    })
    .then([](boost::future<autobahn::wamp_subscription> sub) {
        std::cout << "Subscribed with ID " << sub.get().id() << std::endl;
    });

Here is JavaScript running in Chrome call into C++ running on command line. Both are connected via a WAMP router, in this case Autobahn|Python based.

• Example C++ code
• Example JavaScript code

Building

Notes

• The library code is written in standard C++ 11. Target toolchains currently include clang and gcc. Support for MSVC is tracked on this issue.
• While C++ 11 includes std::future in the standard library, this lacks continuations. boost::future.then allows attaching continuations to futures as outlined in the proposal here. This feature will come to standard C++, but probably not before 2017 (see C++ Standardisation Roadmap)
• Support for when_all and when_any as described in above proposal depends on Boost 1.56 or higher.
• The library and example programs were tested and developed with clang 3.4, libc++ and Boost trunk/1.56 on an Ubuntu 13.10 x86-64 bit system. It also works with gcc 4.8, libstdc++ and Boost trunk/1.56. Your mileage with other versions of the former may vary, but we accept PRs;)

Build tools

Install some libs and build tools (these are for Ubuntu):

sudo apt-get install libbz2-dev libssl-dev cmake

Clang

If you want to work with Clang (rather than GCC), install clang and libc++ (these are for Ubuntu):

sudo apt-get install clang libc++1 libc++-dev
sudo update-alternatives --config c++
# select clang++ in command-line interface

Boost

Most of the time, your distro's Boost libraries will be outdated (unless you're using Arch or Homebrew). Don't waste time with those: to build the latest Boost 1.58 (current release as of 2015/06) from sources

cd ~
wget http://downloads.sourceforge.net/project/boost/boost/1.58.0/boost_1_58_0.tar.bz2
tar xvjf boost_1_58_0.tar.bz2
cd boost_1_58_0
./bootstrap.sh --with-toolset=clang
./b2 toolset=clang cxxflags="-stdlib=libc++" linkflags="-stdlib=libc++" -j 4

Note: The -j 4 option will allow use of 4 cores for building.

To build using GCC instead of Clang:

./bootstrap.sh --with-toolset=gcc
./b2 toolset=gcc -j 4

MsgPack-C

Get MsgPack-C and install:

cd $HOME
git clone https://github.com/msgpack/msgpack-c.git
cd msgpack-c
git checkout cpp-1.1.0
mkdir -p ../build/msgpack-c
cd ../build/msgpack-c
cmake ${HOME}/msgpack-c
make
make install

On FreeBSD, you need to pkg install autotools and invoke gmake instead of make.

Autobahn|Cpp

To get Autobahn|Cpp library and examples, clone the repo

cd $HOME
git clone [email protected]:davidchappelle/AutobahnCpp.git autobahn
cd autobahn

The library is "header-only", means there isn't anything to compile or build. Just include the relevant headers.

Examples

The Autobahn|Cpp repository contains a number of examples that demonstrate all 4 basic patterns of using WAMP:

• Call 1
• Call 2
• Call 3
• Register 1
• Register 2
• Publish 1
• Publish 2
• Publish 3
• Subscribe 1

Building the Examples

For building the examples, add the following to your ~/.profile:

export BOOST_ROOT=${HOME}/boost

Now build all examples:

mkdir -p ${HOME}/build/autobahn
cd ${HOME}/build/autobahn
cmake ${HOME}/autobahn
make -j4

The examples will get built in build/autobahn/examples.

Running the Examples

The examples include a Autobahn|Python based WAMP router and example backend.

To run this, you need Python and pip already installed.

Then, to install Autobahn|Python

pip install autobahn[twisted]

Start the Crossbar hello:cpp example router in a first terminal

cd $CROSSBAR_EXAMPLES/hello/cpp
crossbar start

Then start one of the built C++ examples in a second terminal

cd ${HOME}/build/autobahn
./examples/call1

Documentation

Click here for the Autobahn|Cpp reference documentation.

Get in touch

Get in touch on IRC #autobahn on chat.freenode.net, follow us on Twitter or join the mailing list.

Resources

• ASIO C++11 Examples
• Using Asio with C++11
• C++17: I See a Monad in Your Future!
• Boost Thread
• Boost Issue: when_all
• Boost Issue. when_any
• Boost Issue: future fires twice
• Boost C++ 1y
• Asynchronous API in C++ and the Continuation Monad

Closures Cheatsheet

• [] Capture nothing (or, a scorched earth strategy?)
• [&] Capture any referenced variable by reference
• [=] Capture any referenced variable by making a copy
• [=, &foo] Capture any referenced variable by making a copy, but capture variable foo by reference
• [bar] Capture bar by making a copy; don't copy anything else
• [this] Capture the this pointer of the enclosing class