rdmnet::Broker Class Reference

Overview

Defines an instance of RDMnet broker functionality.

Use the Broker::Settings struct to configure the behavior of the broker. After instantiatiation, call Startup() to start broker services on a set of network interfaces.

Starts some threads to handle messages and connections. The current breakdown (pending concurrency optimization) is:

• Either:
  • One thread per explicitly-specified network interface being listened on, or
  • One thread, if listening on all interfaces
• A platform-dependent number of threads to receive messages from clients, depending on the most efficient way to read large number of sockets on a given platform
• One thread to handle message routing between clients
• One thread to handle periodic cleanup and housekeeping.

Call Shutdown() at exit, when Broker services are no longer needed, or when a setting has changed. The Broker may send notifications through the Broker::NotifyHandler interface.

#include <rdmnet/cpp/broker.h>

Data Structures
struct	DnsAttributes
	Settings for the Broker's DNS Discovery functionality. More...
struct	Limits
	A set of limits for broker operation. More...
class	NotifyHandler
	A callback interface for notifications from the broker. More...
struct	Settings
	A group of settings for broker operation. More...

Public Member Functions
	Broker ()
	Constructs a broker instance. Broker is not running until Broker::Startup() is called.
virtual	~Broker ()
	Destroys a broker instance. Call Broker::Shutdown() first.
	Broker (const Broker &other)=delete
	Brokers cannot be copied.
Broker &	operator= (const Broker &other)=delete
	Brokers cannot be copied.
	Broker (Broker &&other)=default
	Move an instance of broker functionality.
Broker &	operator= (Broker &&other)=default
	Move an instance of broker functionality.
etcpal::Error	Startup (const Settings &settings, etcpal::Logger *logger=nullptr, NotifyHandler *notify=nullptr)
	Start all broker functionality and threads. More...
void	Shutdown (rdmnet_disconnect_reason_t disconnect_reason=kRdmnetDisconnectShutdown)
	Shut down all broker functionality and threads. More...
etcpal::Error	ChangeScope (const std::string &new_scope, rdmnet_disconnect_reason_t disconnect_reason)
	Change the scope on which a broker operates. More...
const Settings &	settings () const
	Get the current settings the broker is using. More...

Member Function Documentation

ChangeScope()

etcpal::Error rdmnet::Broker::ChangeScope	(	const std::string &	new_scope,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Change the scope on which a broker operates.

This function is for changing the scope after Broker::Startup() has been called. To configure the initial scope, use the Broker::Settings::scope member. Sends disconnect messages to all connected clients with the reason given before disconnecting and beginning operations on the new scope.

Parameters

new_scope	The new scope on which the broker should operate.
disconnect_reason	Disconnect reason code to send to all connected clients on the current scope.

Returns

etcpal::Error::Ok(): Scope changed successfully.

kEtcPalErrInvalid: Invalid argument.

kEtcPalErrNotInit: Broker not started.

kEtcPalErrSys: An internal library or system call error occurred.

settings()

const rdmnet::Broker::Settings & rdmnet::Broker::settings

(

)

const

Get the current settings the broker is using.

Can be called even after Shutdown. Useful if you want to shutdown & restart the broker for any reason.

Shutdown()

void rdmnet::Broker::Shutdown

(

rdmnet_disconnect_reason_t

disconnect_reason = kRdmnetDisconnectShutdown

)

Shut down all broker functionality and threads.

Sends disconnect messages to all connected clients, joins all threads and deallocates resources.

Parameters

disconnect_reason

Disconnect reason code to send to all connected clients.

Startup()

etcpal::Error rdmnet::Broker::Startup	(	const Settings &	settings,
		etcpal::Logger *	logger = nullptr,
		NotifyHandler *	notify = nullptr
	)

Start all broker functionality and threads.

If listen_addrs is empty, this returns false. Otherwise, the broker uses the address fields to set up the listening sockets. If the listen_port is 0 and their is only one listen_addr, an ephemeral port is chosen. If there are more listen_addrs, listen_port must not be 0.

Parameters

settings	Settings for the broker to use for this session.
logger	(optional) A class instance that the broker will use to log messages.
notify	(optional) A class instance that the broker will use to send asynchronous notifications about its state.

Returns

etcpal::Error::Ok(): Broker started successfully.

kEtcPalErrInvalid: Invalid argument.

kEtcPalErrNotInit: RDMnet library not initialized.

kEtcPalErrSys: An internal library or system call error occurred.

Other codes translated from system error codes are possible.

---

The documentation for this class was generated from the following files:

• include/rdmnet/cpp/broker.h
• src/rdmnet/broker/broker_api.cpp