/nanomsgxx

Nanomsg binding for C++11

Primary LanguageC++MIT LicenseMIT

nanomsgxx

nanomsgxx is a binding of the nanomsg library for C++11.

The library is still under development and changes may be brought to the API.

Building and installing

Building and installing with waf

nanomsgxx's build is driven by waf, you can get more information about what waf is and how it works here.

waf is packaged with nanomsgxx, all you should need is a python interpreter and running these commands:

./waf configure
./waf build
./waf install

The library and headers will be installed on your system and you'll be able to link your program against libnanomsgxx.

Building and installing with CMake

nanomsgxx also supports CMake builds on various architectures (tested with Windows 10 + VisualStudio2017 and Ubuntu16.04 + g++/clang/c++).

  • install CMake and a CMake generator, e.g. GNU make. See here for a list of available CMake generators and how to use them.

On Linux

mkdir -p build && cd $_

# available build types: Debug, Release
# install location may be adapted with -DCMAKE_INSTALL_PREFIX=path/to/install/nanomsgxx
cmake -DCMAKE_BUILD_TYPE=Release ..

# build example with GNU make
make

# run tests
make test

# install to default location (warning: uninstalling is not that easy)
sudo make install
sudo ldconfig

On Windows using Visual Studio 2017

Since VisualStudio 2017 CMake is supported (see this tutorial).

mkdir build
cd build

cmake -G "Visual Studio 15 2017" ..

This will generate a VisualStudio 2017 nanomsgxx.sln file in folder build/. Building project ALL_BUILD will build the whole solution. Building project INSTALL (with VS2017 started as administrator) will install the project.

Getting started

nanomsgxx aims to provide a very thin abstraction on top of the nanomsg C API, while taking advantage of C++11's features to make the code easier to read and write.

Quick example

#include <iostream>
#include <system_error>
#include <nnxx/message.h>
#include <nnxx/pair.h>
#include <nnxx/socket.h>

int main() {
  try {
    nnxx::socket s1 { nnxx::SP, nnxx::PAIR };
    nnxx::socket s2 { nnxx::SP, nnxx::PAIR };
    const char *addr = "inproc://example";

    s1.bind(addr);
    s2.connect(addr);

    s1.send("Hello World!");

    nnxx::message msg = s2.recv();
    std::cout << msg << std::endl;
    return 0;
  }
  catch (const std::system_error &e) {
    std::cerr << e.what() << std::endl;
    return 1;
  }
}

What did we write?

You've probably recognized most of these calls if you're familiar with nanomsg's API. nanomsgxx uses the nnxx namespace, here we have...

  • declared two socket objects in the SP domain using the PAIR protcol and connected them together
  • sent "Hello World!" from the first socket to the second
  • used the nnxx::socket::recv method to retrieve the message on the receiver side
  • printed the received message to stdout

A few highlights

  • as you can expect from a C++ abstraction there's no need to manually tell when to release resources, this is handled automatically in the destructors
  • the nnxx::message type automatically manages buffers for zero-copy, making high performance code easy to write.
  • error cases are reported throught exceptions that are subclasses of std::system_error

The next step

If you're getting excited about using nanomsgxx in your next C++ project then give the documentation a look and learn more about how it abstracts the pain away from building messages, polling, timeouts and more... The library provides many useful abstractions that make developing with nanomsg easy and safe.

Resources

Documentation: http://achille-roussel.github.io/nanomsgxx

nanomsg website: http://nanomsg.org/index.html

nanomsg sources: https://github.com/nanomsg/nanomsg