Reference

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.

rpc::client

#include "rpc/client.h"

Description

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)
	~client()
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)
nonstd::optional< int64_t >	get_timeout() const
void	set_timeout(int64_t value)
void	clear_timeout()
connection_state	get_connection_state() const
void	wait_all_responses()

rpc::client::client

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

Constructs a client.

Parameters

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.

Details

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.

rpc::client::~client

 rpc::client::~client();

Destructor.

Details

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

rpc::client::call

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.

Parameters

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.

rpc::client::async_call

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.

Parameters

func_name The name of the function to call.

args The arguments to pass to the function.

Details

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).

rpc::client::send

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.

Parameters

func_name The name of the notification to call.

args The arguments to pass to the function.

Details

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).

rpc::client::get_timeout

nonstd::optional< int64_t > rpc::client::get_timeout() const;

Returns the timeout setting of this client in milliseconds.

Details

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.

rpc::client::set_timeout

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

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

rpc::client::clear_timeout

void rpc::client::clear_timeout();

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

rpc::client::get_connection_state

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

Returns the current connection state.

rpc::client::wait_all_responses

void rpc::client::wait_all_responses();

Waits for the completion of all ongoing calls.

rpc::rpc_error

#include "rpc/rpc_error.h"

Description

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()

rpc::rpc_error::get_function_name

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.

rpc::rpc_error::get_error

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

Returns the error object that the server provided.

rpc::server

#include "rpc/server.h"

Description

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. This class is not copyable, but moveable.

Public functions

	server(uint16_t port)
	server(server &&other) noexcept
	server(std::string const &address, uint16_t port)
	~server()
server	operator=(server &&other)
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

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

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

Parameters

port The port number to listen on.

rpc::server::server

 rpc::server::server(server &&other) noexcept;

Move constructor. This is implemented by calling the move assignment operator.

Parameters

other The other instance to move from.

rpc::server::server

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

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

Parameters

address The address to bind to. This only works if oee of your network adapaters control the given address.

port The port number to listen on.

rpc::server::~server

 rpc::server::~server();

Destructor.

Details

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

rpc::server::operator=

server rpc::server::operator=(server &&other);

Move assignment operator.

Parameters

other The other instance to move from.

Return value

The result of the assignment.

rpc::server::run

void rpc::server::run();

Starts the server loop. This is a blocking call.

Details

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 internally as well.

rpc::server::async_run

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.

Parameters

worker_threads The number of worker threads to start.

Details

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.

rpc::server::bind

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.

Parameters

name The name of the functor.

func The functor to bind.

Details

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.

rpc::server::suppress_exceptions

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.

rpc::server::stop

void rpc::server::stop();

Stops the server.

Warn

This should not be called from worker threads.

rpc::server::close_sessions

void rpc::server::close_sessions();

Closes all sessions gracefully.

rpc::this_handler_t

#include "rpc/this_handler.h"

Description

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()

rpc::this_handler_t::respond_error

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.

Parameters

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

rpc::this_handler_t::respond

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.

Parameters

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.

rpc::this_handler_t::disable_response

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).

rpc::this_handler_t::enable_response

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.

rpc::this_handler_t::clear

void rpc::this_handler_t::clear();

Sets all state of the object to default.

rpc::this_server_t

#include "rpc/this_server.h"

Description

Allows controlling the server instance from the currently executing handler.

Public functions

void	stop()
void	cancel_stop()

rpc::this_server_t::stop

void rpc::this_server_t::stop();

Gracefully stops the server.

rpc::this_server_t::cancel_stop

void rpc::this_server_t::cancel_stop();

Cancels a requested stop operation.

rpc::this_session_t

#include "rpc/this_session.h"

Description

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()
session_id_t	id() const

rpc::this_session_t::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.

rpc::this_session_t::id

session_id_t rpc::this_session_t::id() const;

Returns an ID that uniquely identifies a session.

Warn

This is not an ID for the client. If the client disconnects and reconnects, this ID may change. That being said, you can use this ID to store client-specific information *for the duration of the session.

rpc::timeout

#include "rpc/rpc_error.h"

Description

This exception is thrown by the client when either the connection or a call takes more time than it is set in set_timeout.

Public functions

const char *	what() const noexcept override

rpc::timeout::what

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

Describes the exception.