This document is a detailed and (hopefully) complete reference of the public interface of rpclib. For a tutorial, take a look at the Primer. Also, you can find many examples in the Cookbook.


#include "rpc/client.h"


Implements a client that connects to a msgpack-rpc server and is able to call functions synchronously or asynchronously. This is the main interfacing point for implementing client applications.

Use this class to connect to msgpack-rpc servers and call their exposed functions. This class supports calling functions synchronously and asynchronously. When the client object is created, it initiates connecting to the given server asynchronically and disconnects when it is destroyed.

Public functions

client(std::string const &addr, uint16_t port)
RPCLIB_MSGPACK::object_handle call(std::string const &func_name, Args... args)
std::future< RPCLIB_MSGPACK::object_handle > async_call(std::string const &func_name, Args... args)
void send(std::string const &func_name, Args... args)
uint64_t get_timeout() const
void set_timeout(uint64_t value)
connection_state get_connection_state() const
void wait_all_responses()


 rpc::client::client(std::string const &addr, uint16_t port);

Constructs a client.


addr The address of the server to connect to. This might be an IP address or a host name, too.

port The port on the server to connect to.


When a client is constructed, it initiates a connection asynchronically. This means that it will not block while the connection is established. However, when the first call is performed, it might block if the connection was not already established.





During destruction, the connection to the server is gracefully closed. This means that any outstanding reads and writes are completed first.


RPCLIB_MSGPACK::object_handle rpc::client::call(std::string const &func_name, Args... args);

Calls a function with the given name and arguments (if any).

Template parameters

Args The types of the arguments. Each type in this parameter pack have to be serializable by msgpack.


func_name The name of the function to call on the server.

args A variable number of arguments to pass to the called function.

Return value

A RPCLIB_MSGPACK::object containing the result of the function (if any). To obtain a typed value, use the msgpack API.


std::future< RPCLIB_MSGPACK::object_handle > rpc::client::async_call(std::string const &func_name, Args... args);

Calls a function asynchronously with the given name and arguments.

Template parameters

Args The types of the arguments.


func_name The name of the function to call.

args The arguments to pass to the function.


A call is performed asynchronously in the context of the client, i.e. this is not to be confused with parallel execution on the server. This function differs from call in that it does not wait for the result of the function. Instead, it returns a std::future that can be used to retrieve the result later.

Return value

A std::future, possibly holding a future result (which is a RPCLIB_MSGPACK::object).


void rpc::client::send(std::string const &func_name, Args... args);

Sends a notification with the given name and arguments (if any).

Template parameters

Args THe types of the arguments.


func_name The name of the notification to call.

args The arguments to pass to the function.


Notifications are a special kind of calls. They can be used to notify the server, while not expecting a response. In rpclib terminology, a notification is like an async_call without a return value.

!!! warn This function returns immediately (possibly before the notification is written to the socket).


uint64_t rpc::client::get_timeout() const;

Returns the timeout setting of this client in milliseconds.


The timeout is applied to synchronous calls. If the timeout expires without receiving a response from the server,

!!! warn The timeout has no effect on async calls. For those, the preferred timeout mechanism remains using std::future.


void rpc::client::set_timeout(uint64_t value);

Sets the timeout for synchronous calls. For more information, see


connection_state rpc::client::get_connection_state() const;

Returns the current connection state.


void rpc::client::wait_all_responses();

Waits for the completion of all ongoing calls.


#include "rpc/rpc_error.h"


This exception is thrown by the client when the server signals an error during a call.

This type allows clients to handle arbitrary error objects as the msgpack-rpc specification allows. In client code you probably don't want to throw it, hence its constructor is private.

Public functions

std::string get_function_name() const
RPCLIB_MSGPACK::object_handle & get_error()


std::string rpc::rpc_error::get_function_name() const;

Returns the name of the function that was called on the server while the error occurred.


RPCLIB_MSGPACK::object_handle & rpc::rpc_error::get_error();

Returns the error object that the server provided.


#include "rpc/server.h"


Implements a msgpack-rpc server. This is the main interfacing point with the library for creating servers.

The server maintains a registry of function bindings that it uses to dispatch calls. It also takes care of managing worker threads and TCP connections. The server does not start listening right after construction in order to allow binding functions before that. Use the run or async_run functions to start listening on the port.

Public functions

server(uint16_t port)
server(std::string const &address, uint16_t port)
void run()
void async_run(std::size_t worker_threads=1)
void bind(std::string const &name, F func)
void suppress_exceptions(bool suppress)
void stop()
void close_sessions()


 rpc::server::server(uint16_t port);

Constructs a server that listens on the localhost on the specified port.


port The port number to listen on.


 rpc::server::server(std::string const &address, uint16_t port);

Constructs a server that listens on the specified address on the specified port.


port The port number to listen on.





When the server is destroyed, all ongoin sessions are closed gracefully.


void rpc::server::run();

Starts the server loop. This is a blocking call.


First and foremost, running the event loop causes the server to start listening on the specified port. Also, as connections are established and calls are made by clients, the server executes the calls as part of this call. This means that the handlers are executed on the thread that calls run. Reads and writes are initiated by this function


void rpc::server::async_run(std::size_t worker_threads=1);

Starts the server loop on one or more threads. This is a non-blocking call.


worker_threads The number of worker threads to start.


This function behaves similarly to run, except the event loop is optionally started on different threads. Effectively this sets up a worker thread pool for the server. Handlers will be executed on one of the threads.


void rpc::server::bind(std::string const &name, F func);

Binds a functor to a name so it becomes callable via RPC.

Template parameters

F The type of the functor.


name The name of the functor.

func The functor to bind.


This function template accepts a wide range of callables. The arguments and return types of these callables should be serializable by msgpack. bind effectively generates a suitable, light-weight compile-time wrapper for the functor.


void rpc::server::suppress_exceptions(bool suppress);

Sets the exception behavior in handlers. By default, handlers throwing will crash the server. If suppressing is on, the server will try to gather textual data and return it to the client as an error response.

!!! warn Setting this flag only affects subsequent connections.


void rpc::server::stop();

Stops the server.

!!! warn This should not be called from worker threads.


void rpc::server::close_sessions();

Closes all sessions gracefully.


#include "rpc/this_handler.h"


Encapsulates information about the currently executing handler. This is the interface through which bound functions may return errors, arbitrary type responses or prohibit sending a response.

Public functions

void respond_error(T &&err_obj)
void respond(T &&resp_obj)
void disable_response()
void enable_response()
void clear()


void rpc::this_handler_t::respond_error(T &&err_obj);

Sets an arbitrary object to be sent back as an error response to the client.

Template parameters

T The type of the error object.


err_obj The error object. This can be anything that is possible to encode with messagepack (even custom structures).


void rpc::this_handler_t::respond(T &&resp_obj);

Sets an arbitrary object to be sent back as the response to the call.

Template parameters

T The type of the response object.


resp_obj The response object. This can be anything that is possible to encode with messagepack (even custom structures).

!!! warn The normal return value of the function (if any) will be ignored if a special response is set.


void rpc::this_handler_t::disable_response();

Instructs the server to not send a response to the client (ignoring any errors and return values).

!!! warn It is unusual to not send a response to requests, and doing so might cause problems in the client (depending on its implementation).


void rpc::this_handler_t::enable_response();

Enables sending a response to the call. Sending the response is by default enabled. Enabling the response multiple times have no effect.


void rpc::this_handler_t::clear();

Sets all state of the object to default.


#include "rpc/this_server.h"


Allows controlling the server instance from the currently executing handler.

Public functions

void stop()
void cancel_stop()


void rpc::this_server_t::stop();

Gracefully stops the server.


void rpc::this_server_t::cancel_stop();

Cancels a requested stop operation.


#include "rpc/this_session.h"


Encapsulates information about the server session/connection this handler is running in. This is the interface through which bound functions may interact with the session.

Public functions

void post_exit()


void rpc::this_session_t::post_exit();

Gracefully exits the session (i.e. ongoing writes and reads are completed; queued writes and reads are not).

!!! warn Use this function if you need to close the connection from a handler.


#include ""


Public functions

const char * what() const noexcept override


const char * rpc::timeout::what() const noexcept override;