Application-facing wrapper for Agent and Agent subclasses. More...

#include <agent_app.hpp>

Inheritance diagram for Mads::AgentAppT< AgentT >:

Classes
struct	CliOptions
	Common options parsed for agent executables. More...

struct	CryptoOptions
	CURVE encryption options parsed from the command line. More...

Public Member Functions
	AgentAppT (std::string name, std::string settings_uri)
	Construct an AgentAppT with an owned cxxopts parser.

cxxopts::OptionAdder	options ()
	Access the common option adder for fluent cxxopts declarations.

cxxopts::Options &	raw_options ()
	Access the owned cxxopts parser.

const cxxopts::Options &	raw_options () const
	Access the owned cxxopts parser.

void	add_common_options ()
	Add common MADS executable options to the owned parser.

void	add_agent_identity_options ()
	Add optional agent identity options.

void	set_agent_name (std::string name)
	Override the wrapped agent name before initialization.

void	add_dont_block_option ()
	Add the non-blocking receive option.

void	add_queue_size_option ()
	Add the ZMQ socket queue size option.

cxxopts::ParseResult &	parse_options (int argc, char *argv[])
	Parse the owned cxxopts parser.

void	init (const cxxopts::ParseResult &parsed, std::string default_settings_uri=SETTINGS_URI, bool install_watchdog=true)
	Apply parsed CLI options and initialize the wrapped agent.

void	fetch_settings (const cxxopts::ParseResult &parsed, std::string default_settings_uri=SETTINGS_URI)
	Apply parsed CLI options and fetch settings (and any broker-served attachment) without binding the wrapped agent to a settings section.

void	enable_events (bool enabled=true)
	Enable automatic startup and shutdown event registration.

void	connect (std::chrono::milliseconds delay=std::chrono::milliseconds(250))
	Connect the wrapped agent and optionally register startup.

void	disconnect ()
	Optionally register shutdown and disconnect the wrapped agent.

const nlohmann::json &	settings_json () const
	Return cached settings loaded during init().

void	apply_receive_timeout ()
	Apply receive_timeout from cached settings when present.

void	apply_queue_size ()
	Apply queue size from CLI or cached settings when present.

bool	restart_if_requested (char *argv[], std::ostream &out=std::cout)
	Restart the current executable if requested by remote control.

Static Public Member Functions
template<typename SaveAgentT >
static int	handle_standard_exit_options (const cxxopts::ParseResult &parsed, const cxxopts::Options &parser, char *argv[], std::string default_settings_uri=SETTINGS_URI, std::ostream &out=std::cout, std::ostream &err=std::cerr)
	Handle standard options that terminate an executable early.

Detailed Description

template<typename AgentT>
class Mads::AgentAppT< AgentT >

Application-facing wrapper for Agent and Agent subclasses.

AgentAppT keeps messaging behavior in the wrapped Agent-derived class while collecting repetitive command-line and startup operations used by agent executables. Use AgentApp for a plain Agent and AgentAppFor<T> for an existing Agent subclass such as Bridge, Dealer, Worker, Logger, or Image.

Minimal usage:

int main(int argc, char *argv[]) {
  Mads::AgentApp agent{argv[0], SETTINGS_URI};
  agent.add_common_options();
  agent.options()
    ("my-option", "An additional option flag");
 
  auto parsed = agent.parse_options(argc, argv);
  if (int rc = Mads::AgentApp::handle_standard_exit_options<Mads::AgentApp>(
          parsed, agent.raw_options(), argv);
      rc >= 0) {
    return rc;
  }
 
  agent.init(parsed);
  agent.enable_events();
  agent.connect();
  agent.info();
 
  std::chrono::milliseconds time{100};
  agent.loop([&]() -> std::chrono::milliseconds {
    // Stop this agent programmatically when done:
    if (work_finished) agent.runtime()->stop();
    return 0ms;
  }, time);
 
  agent.disconnect();
  agent.restart_if_requested(argv);
  return 0;
}

Run state follows the Mads::Runtime model (see RUNTIME.md): the loop ends when the agent's own Runtime is stopped (agent.runtime()->stop()), on a process-wide stop (SIGINT/SIGTERM, remote shutdown/restart commands, or Mads::Runtime::stop_process()), or when the agent itself is disconnected. Other agents hosted in the same process are unaffected unless they share this agent's Runtime via Agent::set_runtime().

Existing Agent subclasses can be wrapped without changing the subclass:

Mads::AgentAppFor<Mads::Bridge> bridge{argv[0], SETTINGS_URI};

bridge.route();

Mads::AgentAppFor

AgentAppT< AgentT > AgentAppFor

Definition agent_app.hpp:657

Template Parameters

AgentT Agent or an Agent-derived class constructible from (std::string, std::string).

Definition at line 98 of file agent_app.hpp.

Constructor & Destructor Documentation

◆ AgentAppT()

template<typename AgentT >

Mads::AgentAppT< AgentT >::AgentAppT	(	std::string	name,
		std::string	settings_uri
	)

inline

Construct an AgentAppT with an owned cxxopts parser.

Parameters

name	Agent name or executable path, following Agent constructor semantics.
settings_uri	Settings path or broker URI.

Definition at line 155 of file agent_app.hpp.

Member Function Documentation

◆ add_agent_identity_options()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::add_agent_identity_options ( )

inline

Add optional agent identity options.

Definition at line 209 of file agent_app.hpp.

◆ add_common_options()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::add_common_options ( )

inline

Add common MADS executable options to the owned parser.

Definition at line 182 of file agent_app.hpp.

References Mads::exec_dir().

◆ add_dont_block_option()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::add_dont_block_option ( )

inline

Add the non-blocking receive option.

Definition at line 242 of file agent_app.hpp.

◆ add_queue_size_option()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::add_queue_size_option ( )

inline

Add the ZMQ socket queue size option.

Definition at line 250 of file agent_app.hpp.

◆ apply_queue_size()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::apply_queue_size ( )

inline

Apply queue size from CLI or cached settings when present.

Definition at line 469 of file agent_app.hpp.

◆ apply_receive_timeout()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::apply_receive_timeout ( )

inline

Apply receive_timeout from cached settings when present.

Definition at line 455 of file agent_app.hpp.

◆ connect()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::connect ( std::chrono::milliseconds delay = std::chrono::milliseconds(250) )

inline

Connect the wrapped agent and optionally register startup.

Definition at line 430 of file agent_app.hpp.

◆ disconnect()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::disconnect ( )

inline

Optionally register shutdown and disconnect the wrapped agent.

Definition at line 440 of file agent_app.hpp.

◆ enable_events()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::enable_events ( bool enabled = true )

inline

Enable automatic startup and shutdown event registration.

Definition at line 425 of file agent_app.hpp.

◆ fetch_settings()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::fetch_settings	(	const cxxopts::ParseResult &	parsed,
		std::string	default_settings_uri = `SETTINGS_URI`
	)

inline

Apply parsed CLI options and fetch settings (and any broker-served attachment) without binding the wrapped agent to a settings section.

Mirrors init(), but calls Agent::fetch_settings() instead of Agent::init(). Useful when the settings section name itself depends on something only known after inspecting settings/attachment (e.g. a plugin loader resolving which plugin file to load). A later call to init() reuses the CLI options resolved here (so –room service discovery only runs once) and completes section binding.

Parameters

parsed	cxxopts parse result.
default_settings_uri	Settings URI to use when –settings is absent.

Definition at line 413 of file agent_app.hpp.

◆ handle_standard_exit_options()

template<typename AgentT >

template<typename SaveAgentT >

static int Mads::AgentAppT< AgentT >::handle_standard_exit_options	(	const cxxopts::ParseResult &	parsed,
		const cxxopts::Options &	parser,
		char *	argv[],
		std::string	default_settings_uri = `SETTINGS_URI`,
		std::ostream &	out = `std::cout`,
		std::ostream &	err = `std::cerr`
	)

inlinestatic

Handle standard options that terminate an executable early.

Handles –help, –version, and –save-settings. Returns -1 when no early-exit option was present; otherwise returns the process exit code that should be returned by main().

Template Parameters

SaveAgentT Agent type used for –save-settings.

Parameters

parsed	cxxopts parse result.
parser	cxxopts parser used to print help.
argv	Argument vector from main().
default_settings_uri	Settings URI to use when –settings is absent.
out	Stream for normal output.
err	Stream for error output.

Returns: -1 when no early exit is needed, otherwise EXIT_SUCCESS or EXIT_FAILURE.

Definition at line 308 of file agent_app.hpp.

◆ init()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::init	(	const cxxopts::ParseResult &	parsed,
		std::string	default_settings_uri = `SETTINGS_URI`,
		bool	install_watchdog = `true`
	)

inline

Apply parsed CLI options and initialize the wrapped agent.

Parameters

parsed	cxxopts parse result.
default_settings_uri	Settings URI to use when –settings is absent.
install_watchdog	Whether Agent::init() should install the loop watchdog.

Definition at line 389 of file agent_app.hpp.

◆ options()

template<typename AgentT >

cxxopts::OptionAdder Mads::AgentAppT< AgentT >::options ( )

inline

Access the common option adder for fluent cxxopts declarations.

Returns: A cxxopts option adder bound to the owned parser.

Definition at line 163 of file agent_app.hpp.

◆ parse_options()

template<typename AgentT >

cxxopts::ParseResult & Mads::AgentAppT< AgentT >::parse_options	(	int	argc,
		char *	argv[]
	)

inline

Parse the owned cxxopts parser.

Invalid command lines are reported with parser help and terminate with EXIT_FAILURE.

Parameters

argc	Argument count from main().
argv	Argument vector from main().

Returns: Parsed cxxopts result owned by this object.

Definition at line 266 of file agent_app.hpp.

◆ raw_options() [1/2]

template<typename AgentT >

cxxopts::Options & Mads::AgentAppT< AgentT >::raw_options ( )

inline

Access the owned cxxopts parser.

Returns: Mutable reference to the owned parser.

Definition at line 170 of file agent_app.hpp.

◆ raw_options() [2/2]

template<typename AgentT >

const cxxopts::Options & Mads::AgentAppT< AgentT >::raw_options ( ) const

inline

Access the owned cxxopts parser.

Returns: Const reference to the owned parser.

Definition at line 177 of file agent_app.hpp.

◆ restart_if_requested()

template<typename AgentT >

bool Mads::AgentAppT< AgentT >::restart_if_requested	(	char *	argv[],
		std::ostream &	out = `std::cout`
	)

inline

Restart the current executable if requested by remote control.

Parameters

argv	Original argv from main().
out	Stream for restart status output.

Returns: true when a restart was requested and exec was attempted.

Definition at line 489 of file agent_app.hpp.

◆ set_agent_name()

template<typename AgentT >

void Mads::AgentAppT< AgentT >::set_agent_name ( std::string name )

inline

Override the wrapped agent name before initialization.

Keeps Agent constructor semantics by dropping a command prefix before the last '-' when present.

Definition at line 224 of file agent_app.hpp.

◆ settings_json()

template<typename AgentT >

const nlohmann::json & Mads::AgentAppT< AgentT >::settings_json ( ) const

inline

Return cached settings loaded during init().

Definition at line 450 of file agent_app.hpp.

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

src/agent_app.hpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ AgentAppT()

Member Function Documentation

◆ add_agent_identity_options()

◆ add_common_options()

◆ add_dont_block_option()

◆ add_queue_size_option()

◆ apply_queue_size()

◆ apply_receive_timeout()

◆ connect()

◆ disconnect()

◆ enable_events()

◆ fetch_settings()

◆ handle_standard_exit_options()

◆ init()

◆ options()

◆ parse_options()

◆ raw_options() [1/2]

◆ raw_options() [2/2]

◆ restart_if_requested()

◆ set_agent_name()

◆ settings_json()