nngpp

C++ wrapper around the nanomsg NNG API

What's nanomsg? In a nutshell it's a spiritual successor to ZeroMQ, and NNG is its latest incarnation.

Features

Header-only -- just add the include directory to your includes
Supports all nng protocols, transports and supplemental code
Zero overhead -- no virtual functions, no extra allocations or copies
Owning RAII classes, e.g. nng::socket and nng::msg
Non-owning views, e.g. nng::socket_view and nng::msg_view
Failure is communicated with exceptions instead of error codes
Compatible with C++11 but uses C++17 features when available

Hello world

#include <nngpp/nngpp.h>
#include <nngpp/protocol/req0.h>
#include <nngpp/protocol/rep0.h>
#include <cstdio>

int main() try {
	// create a socket for the rep protocol
	nng::socket rep_sock = nng::rep::open();
	
	// rep starts listening using the tcp transport
	rep_sock.listen( "tcp://localhost:8000" );
	
	// create a socket for the req protocol
	nng::socket req_sock = nng::req::open();
	
	// req dials and establishes a connection
	req_sock.dial( "tcp://localhost:8000" );
	
	// req sends "hello" including the null terminator
	req_sock.send("hello");
	
	// rep receives a message
	nng::buffer rep_buf = rep_sock.recv();
	
	// check the content
	if( rep_buf == "hello" ) {
		// rep sends "world" in response
		rep_sock.send("world");
	}
	
	// req receives "world"
	nng::buffer req_buf = req_sock.recv();
}
catch( const nng::exception& e ) {
	// who() is the name of the nng function that produced the error
	// what() is a description of the error code
	printf( "%s: %s\n", e.who(), e.what() );
	return 1;
}
// req_buf is freed
// rep_buf is freed
// req_sock is closed
// rep_sock is closed

Demos

All 5 nng demos have been ported to nngpp to illustrate the use of the library. I have kept the original structure of the demos intact, just replacing the nng API with nngpp. This allows for easy comparison with the nng demos, but may mean they are non-idiomatic in places. See the demo directory.

Dependencies

Since nngpp is a wrapper around nng, you will need to link with libnng.

If you built nng without tls support: -lnng -lpthread
If you built nng with tls support: -lnng -lmbedtls -lmbedx509 -lmbedcrypto -lpthread

Design

The nng API consists of a number of conceptual objects, such as 'socket' and 'pipe'. Each of these is identified and referred to by a handle, which is typically either a pointer or a (structured) integer id.

In nngpp these handles are wrapped in views that expose all of the corresponding functionality as member functions. For example, the nng_socket handle is wrapped by a nng::socket_view that has the member function dial(), which calls the nng function nng_dial(). All views provide a common set of member functions:

default constructor of null handle
implicit construction from a given handle
get() -- get the handle
operator->() (for pointer handles) -- access to the handle's members
operator bool() -- test for the presence of a non-null handle

Most of these conceptual objects are also resources, i.e. they must be acquired and released. To manage the ownership of these resources, nngpp provides RAII classes, such as nng::socket. Each RAII class is an extension of the corresponding view and has the following:

default constructor of null handle
explicit construction from a given handle
specific constructors -- acquire a new handle using the given arguments
destructor -- release the resource (if held)
move -- transfer ownership to another instance
copy (if possible) -- duplicate the resource
release() -- get the underlying handle, detaching its ownership from the object

In addition to constructors, there are make functions:

auto msg1 = nng::make_msg(32);  // acquire using make function
 
nng::msg msg2(32);              // acquire using constructor

The make function is needed to acquire with zero arguments, e.g.

auto mtx1 = nng::make_mtx();  // acquire new mutex
 
nng::mtx mtx2;                // default constructor gives null mutex

Summary

Name	nng handle	nngpp view	nngpp RAII
socket	`nng_socket`	`nng::socket_view`	`nng::socket`
context	`nng_ctx`	`nng::ctx_view`	`nng::ctx`
dialer	`nng_dialer`	`nng::dialer_view`	`nng::dialer`
listener	`nng_listener`	`nng::listener_view`	`nng::listener`
pipe	`nng_pipe`	`nng::pipe_view`	`nng::pipe`
message	`nng_msg*`	`nng::msg_view`	`nng::msg`
async i/o	`nng_aio*`	`nng::aio_view`	`nng::aio`
url	`nng_url*`	`nng::url_view`	`nng::url`
buffer	`void*, size_t`	`nng::view`	`nng::buffer`
stat	`nng_stat*`	`nng::stat_view`	`nng::stat`
thread	`nng_thread*`	`nng::thread_view`	`nng::thread`
mutex	`nng_mtx*`	`nng::mtx_view`	`nng::mtx`
condition variable	`nng_cv*`	`nng::cv_view`	`nng::cv`
tls config	`nng_tls_config*`	`nng::tls::config_view`	`nng::tls::config`
http client	`nng_http_client*`	`nng::http::client_view`	`nng::http::client`
http connection	`nng_http_conn*`	`nng::http::conn_view`	`nng::http::conn`
http handler	`nng_http_handler*`	`nng::http::handler_view`	`nng::http::handler`
http request	`nng_http_req*`	`nng::http::req_view`	`nng::http::req`
http response	`nng_http_res*`	`nng::http::res_view`	`nng::http::res`
http server	`nng_http_server*`	`nng::http::server_view`	`nng::http::server`
stream	`nng_stream*`	`nng::stream::stream_view`	`nng::stream::stream`
stream dialer	`nng_stream_dialer*`	`nng::stream::dialer_view`	`nng::stream::dialer`
stream listener	`nng_stream_listener*`	`nng::stream::listener_view`	`nng::stream::listener`

Error handling

Many of nng's functions can fail and do so by returning an error code. In nngpp, the wrapper will throw these error codes as an nng::exception that has:

get_error() -- get the error code
who() -- name of the nng function that failed
what() -- description of the error

All nngpp functions that don't throw are marked noexcept.

Failure in destructors

The following objects have destructors that can fail:

nng::socket
nng::ctx
nng::listener
nng::dialer
nng::pipe

In this case the destructor completes without throwing.

Protocol versioning

NNG has version numbers on its protocols, e.g. pair0 and pair1. This is expressed in nngpp with namespaces:

auto s0 = nng::pair::v0::open();  // version 0

auto s1 = nng::pair::v1::open();  // version 1

auto s2 = nng::pair::open();      // latest version (currently v1)

An inline namespace is used for the latest version of each protocol.

Socket options

Some objects (socket, ctx, dialer, listener, pipe) have options that can be get/set. The nng API requires that you use the correct type of getter/setter function for each option. For example, the receive timeout socket option (NNG_OPT_RECVTIMEO) is of type nng_duration and must set with nng_setopt_ms(). Another issue is that some options are read-only. In both cases you will only find out at run-time if there is a problem with your code.

In nngpp every option on every object has a dedicated getter and setter of the correct type:

nng::set_opt_recv_timeout( socket, 1000 );
nng_duration timeout = nng::get_opt_recv_timeout( socket );

If an option is read-only it will have no setter -- you will know at compile time or earlier if you are trying to set a read-only option.

These dedicated getters and setters are free-standing functions, rather than members, as there are some options that are only available with certain transports. For example, with the TCP transport the socket has a keep alive option:

bool keep_alive = nng::tcp::get_opt_keep_alive( socket );

brugr9/nngpp