shuyunqi / autobahncpp

WAMP for C++ 11 on Boost/Asio

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::any
• boost::asio

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", {23, 777})
.then(
   [&](future<any> f) {
		cout << "Got call result " << any_cast<uint64_t> (f.get()) << endl;
	});

Registering a remoted Procedure

auto r1 = session.provide("com.myapp.cpp.square",
   [](const anyvec& args, const anymap& kwargs) {
      cout << "Procedure is invoked .." << endl;
      uint64_t x = any_cast<uint64_t> (args[0]);
      return x * x;
   })
.then(
   [](future<registration> reg) {
      cout << "Registered with ID " << reg.get().id << endl;
   });

Publishing an Event

session.publish("com.myapp.topic2", {23, true, string("hello")});

Publishing an Event (acknowledged)

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

auto p1 = session.publish("com.myapp.topic2", {23, true, string("hello")}, opts)
.then(
   [](future<publication> pub) {
      cout << "Published with ID " << pub.get().id << endl;
   });

Subscribing to a Topic

auto s1 = session.subscribe("com.myapp.topic1",
   [](const anyvec& args, const anymap& kwargs) {
      cout << "Got event: " << any_cast<uint64_t>(args[0]) << endl;
   })
.then(
   [](future<subscription> sub) {
      cout << "Subscribed with ID " << sub.get().id << 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 2015 (see C++ Standardisation Roadmap)
• Support for when_all and when_any as described in above proposal depends on Boost 1.56 (upcoming release as of 31/03/2014) 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 ruby libtool autoconf scons

Clang

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

sudo apt-get install clang libc++1 libc++-dev

Boost

Most of the time, your distro's Boost libraries will be outdated. Don't waste time with the latter: to build the latest Boost 1.57 (current release as of 2015/03) from sources

cd ~
wget http://downloads.sourceforge.net/project/boost/boost/1.57.0/boost_1_57_0.tar.bz2
tar xvjf boost_1_57_0.tar.bz2
cd boost_1_57_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 build with Clang:

cd $HOME
git clone https://github.com/msgpack/msgpack-c.git
cd msgpack-c
git checkout cpp-1.0.1
./bootstrap
CXX=`which clang++` CC=`which clang` CXXFLAGS="-std=c++11 -stdlib=libc++" \
   LDFLAGS="-stdlib=libc++" ./configure --prefix=$HOME/msgpack_clang
make
make install

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

To build with GCC instead of clang:

./configure --prefix=$HOME/msgpack_gcc

Autobahn|Cpp

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

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

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:

## Use clang
##
export CC='clang'
export CXX='clang++'

## Libaries (clang based)
##
export BOOST_ROOT=${HOME}/boost_trunk_clang
export LD_LIBRARY_PATH=${BOOST_ROOT}/stage/lib:${LD_LIBRARY_PATH}

export MSGPACK_ROOT=${HOME}/msgpack_clang
export LD_LIBRARY_PATH=${MSGPACK_ROOT}/lib:${LD_LIBRARY_PATH}

For building with GCC, use the following

## Use GNU
##
export CC='gcc'
export CXX='g++'

## Libraries (GCC based)
##
export BOOST_ROOT=${HOME}/boost_trunk_gcc
export LD_LIBRARY_PATH=${BOOST_ROOT}/stage/lib:${LD_LIBRARY_PATH}

export MSGPACK_ROOT=${HOME}/msgpack_gcc
export LD_LIBRARY_PATH=${MSGPACK_ROOT}/lib:${LD_LIBRARY_PATH}

Now build all examples:

cd autobahn/examples
scons -j 4

The examples will get built in autobahn/build/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 autobahn
./build/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