provides an API to the goby-acomms Queuing Library. More...

#include <goby/acomms/queue.h>

Public Member Functions
	QueueManager ()
	constructor

	~QueueManager ()=default
	destructor

Initialization Methods
These methods are intended to be called before doing any work with the class.
void	set_cfg (const protobuf::QueueManagerConfig &cfg)
	Set (and overwrite completely if present) the current configuration. (protobuf::QueueManagerConfig defined in acomms_queue.proto)

void	merge_cfg (const protobuf::QueueManagerConfig &cfg)
	Set (and merge "repeat" fields) the current configuration. (protobuf::QueueManagerConfig defined in acomms_queue.proto)

template<typename ProtobufMessage >
void	add_queue (const protobuf::QueuedMessageEntry &queue_cfg)
	Add a DCCL queue for use with QueueManager. Note that the queue must be added before receiving messages with QueueManager.

void	add_queue (const google::protobuf::Descriptor *desc, const protobuf::QueuedMessageEntry &queue_cfg)
	Alternative method for adding Queues when using Dynamic Protobuf Messages.

Application level Push/Receive Methods
These methods are the primary higher level interface to the QueueManager. From here you can push messages and set the callbacks to use on received messages.
void	push_message (const google::protobuf::Message &new_message)
	Push a message (and add the queue if it does not exist)

void	push_message (const google::protobuf::Message &new_message, const protobuf::QueuedMessageMeta *meta)

void	flush_queue (const protobuf::QueueFlush &flush)
	Flush (delete all messages in) a queue.

Modem Slots
These methods are the interface to the QueueManager from the modem driver.
void	handle_modem_data_request (protobuf::ModemTransmission *msg)
	Finds data to send to the modem.

void	handle_modem_receive (const protobuf::ModemTransmission &message)
	Receive incoming data from the modem.

Control
Call these methods when you want the QueueManager to perform time sensitive tasks (such as expiring old messages)
void	do_work ()
	Calculates which messages have expired and emits the goby::acomms::QueueManager::signal_expire as necessary.

Informational Methods
void	info_all (std::ostream *os) const
	Writes a human readable summary (including DCCLCodec info) of all loaded queues.

template<typename ProtobufMessage >
void	info (std::ostream *os) const
	Writes a human readable summary (including DCCLCodec info) of the queue for the provided DCCL type to the stream provided.

void	info (const google::protobuf::Descriptor desc, std::ostream os) const
	An alterative form for getting information for Queues for message types not known at compile-time ("dynamic").

const std::string &	glog_push_group ()

const std::string &	glog_pop_group ()

const std::string &	glog_priority_group ()

const std::string &	glog_out_group ()

const std::string &	glog_in_group ()

std::string	msg_string (const google::protobuf::Descriptor *desc)

int	modem_id ()
	The current modem ID (MAC address) of this node.

protobuf::QueuedMessageMeta	meta_from_msg (const google::protobuf::Message &msg)

Application Signals
boost::signals2::signal< void(const protobuf::ModemTransmission &ack_msg, const google::protobuf::Message &orig_msg)>	signal_ack
	Signals when acknowledgment of proper message receipt has been received. This is only sent for queues with queue.ack == true with an explicit destination (ModemMessageBase::dest() != 0)

boost::signals2::signal< void(const google::protobuf::Message &msg)>	signal_receive
	Signals when a DCCL message is received.

boost::signals2::signal< void(const google::protobuf::Message &orig_msg)>	signal_expire
	Signals when a message is expires (exceeds its time-to-live or ttl) before being sent (if queue.ack == false) or before being acknowledged (if queue.ack == true).

boost::signals2::signal< void(const protobuf::ModemTransmission &request_msg, google::protobuf::Message *data_msg)>	signal_data_on_demand
	Forwards the data request to the application layer. This advanced feature is used when queue.encode_on_demand == true and allows for the application to provide data immediately before it is actually sent (for highly time sensitive data)

boost::signals2::signal< void(protobuf::QueueSize size)>	signal_queue_size_change
	Signals when any queue changes size (message is popped or pushed)

boost::signals2::signal< void(protobuf::QueuedMessageMeta *meta, const google::protobuf::Message &data_msg, int modem_id)>	signal_out_route
	Used by a router to change next-hop destination (in meta)

boost::signals2::signal< void(const protobuf::QueuedMessageMeta &meta, const google::protobuf::Message &data_msg, int modem_id)>	signal_in_route
	Used by a router to intercept messages and requeue them if desired.

class	Queue

Detailed Description

provides an API to the goby-acomms Queuing Library.

See also: acomms_queue.proto and acomms_modem_message.proto for definition of Google Protocol Buffers messages (namespace goby::acomms::protobuf).

Definition at line 66 of file queue_manager.h.

Constructor & Destructor Documentation

◆ QueueManager()

goby::acomms::QueueManager::QueueManager ( )

constructor

◆ ~QueueManager()

goby::acomms::QueueManager::~QueueManager ( )

default

destructor

Member Function Documentation

◆ add_queue() [1/2]

void goby::acomms::QueueManager::add_queue	(	const google::protobuf::Descriptor *	desc,
		const protobuf::QueuedMessageEntry &	queue_cfg
	)

Alternative method for adding Queues when using Dynamic Protobuf Messages.

◆ add_queue() [2/2]

template<typename ProtobufMessage >

void goby::acomms::QueueManager::add_queue ( const protobuf::QueuedMessageEntry & queue_cfg )

inline

Add a DCCL queue for use with QueueManager. Note that the queue must be added before receiving messages with QueueManager.

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Definition at line 89 of file queue_manager.h.

◆ do_work()

void goby::acomms::QueueManager::do_work ( )

Calculates which messages have expired and emits the goby::acomms::QueueManager::signal_expire as necessary.

◆ flush_queue()

void goby::acomms::QueueManager::flush_queue ( const protobuf::QueueFlush & flush )

Flush (delete all messages in) a queue.

Parameters

flush QueueFlush object containing details about queue to flush

◆ glog_in_group()

const std::string & goby::acomms::QueueManager::glog_in_group ( )

inline

Definition at line 170 of file queue_manager.h.

◆ glog_out_group()

const std::string & goby::acomms::QueueManager::glog_out_group ( )

inline

Definition at line 169 of file queue_manager.h.

◆ glog_pop_group()

const std::string & goby::acomms::QueueManager::glog_pop_group ( )

inline

Definition at line 167 of file queue_manager.h.

◆ glog_priority_group()

const std::string & goby::acomms::QueueManager::glog_priority_group ( )

inline

Definition at line 168 of file queue_manager.h.

◆ glog_push_group()

const std::string & goby::acomms::QueueManager::glog_push_group ( )

inline

Definition at line 166 of file queue_manager.h.

◆ handle_modem_data_request()

void goby::acomms::QueueManager::handle_modem_data_request ( protobuf::ModemTransmission * msg )

Finds data to send to the modem.

Data from the highest priority queue(s) will be combined to form a message equal or less than the size requested in ModemMessage message_in. If using one of the classes inheriting ModemDriverBase, this method should be connected to ModemDriverBase::signal_data_request.

Parameters

msg	The ModemTransmission containing information about the data request and is the place where the request data will be stored (in the repeated field ModemTransmission::frame).

◆ handle_modem_receive()

void goby::acomms::QueueManager::handle_modem_receive ( const protobuf::ModemTransmission & message )

Receive incoming data from the modem.

If using one of the classes inheriting ModemDriverBase, this method should be bound and passed to ModemDriverBase::signal_receive.

Parameters

message The received ModemMessage.

◆ info() [1/2]

void goby::acomms::QueueManager::info	(	const google::protobuf::Descriptor *	desc,
		std::ostream *	os
	)		const

An alterative form for getting information for Queues for message types not known at compile-time ("dynamic").

◆ info() [2/2]

template<typename ProtobufMessage >

void goby::acomms::QueueManager::info ( std::ostream * os ) const

inline

Writes a human readable summary (including DCCLCodec info) of the queue for the provided DCCL type to the stream provided.

Template Parameters

ProtobufMessage Any Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Parameters

os	Pointer to a stream to write this information

Definition at line 158 of file queue_manager.h.

◆ info_all()

void goby::acomms::QueueManager::info_all ( std::ostream * os ) const

Writes a human readable summary (including DCCLCodec info) of all loaded queues.

Parameters

os	Pointer to a stream to write this information

◆ merge_cfg()

void goby::acomms::QueueManager::merge_cfg ( const protobuf::QueueManagerConfig & cfg )

Set (and merge "repeat" fields) the current configuration. (protobuf::QueueManagerConfig defined in acomms_queue.proto)

◆ meta_from_msg()

protobuf::QueuedMessageMeta goby::acomms::QueueManager::meta_from_msg ( const google::protobuf::Message & msg )

inline

Definition at line 180 of file queue_manager.h.

◆ modem_id()

int goby::acomms::QueueManager::modem_id ( )

inline

The current modem ID (MAC address) of this node.

Definition at line 178 of file queue_manager.h.

◆ msg_string()

std::string goby::acomms::QueueManager::msg_string ( const google::protobuf::Descriptor * desc )

inline

Definition at line 172 of file queue_manager.h.

◆ push_message() [1/2]

void goby::acomms::QueueManager::push_message ( const google::protobuf::Message & new_message )

Push a message (and add the queue if it does not exist)

Parameters

new_message DCCL message to push.

◆ push_message() [2/2]

void goby::acomms::QueueManager::push_message	(	const google::protobuf::Message &	new_message,
		const protobuf::QueuedMessageMeta *	meta
	)

◆ set_cfg()

void goby::acomms::QueueManager::set_cfg ( const protobuf::QueueManagerConfig & cfg )

Set (and overwrite completely if present) the current configuration. (protobuf::QueueManagerConfig defined in acomms_queue.proto)

Friends And Related Symbol Documentation

◆ Queue

friend class Queue

friend

Definition at line 261 of file queue_manager.h.

Member Data Documentation

◆ signal_ack

boost::signals2::signal<void(const protobuf::ModemTransmission& ack_msg, const google::protobuf::Message& orig_msg)> goby::acomms::QueueManager::signal_ack

Signals when acknowledgment of proper message receipt has been received. This is only sent for queues with queue.ack == true with an explicit destination (ModemMessageBase::dest() != 0)

"ack_msg": a message containing details of the acknowledgment. "orig_msg": the original message for which this acknowledgment applies.

Definition at line 200 of file queue_manager.h.

◆ signal_data_on_demand

boost::signals2::signal<void(const protobuf::ModemTransmission& request_msg, google::protobuf::Message* data_msg)> goby::acomms::QueueManager::signal_data_on_demand

Forwards the data request to the application layer. This advanced feature is used when queue.encode_on_demand == true and allows for the application to provide data immediately before it is actually sent (for highly time sensitive data)

"request_msg": the details of the requested data. (protobuf::ModemDataRequest is defined in acomms_modem_message.proto) "data_msg": pointer to store the supplied data. The message is of the type for this queue.

Definition at line 218 of file queue_manager.h.

◆ signal_expire

boost::signals2::signal<void(const google::protobuf::Message& orig_msg)> goby::acomms::QueueManager::signal_expire

Signals when a message is expires (exceeds its time-to-live or ttl) before being sent (if queue.ack == false) or before being acknowledged (if queue.ack == true).

"orig_msg": the original message which expired before transmission.

Definition at line 210 of file queue_manager.h.

◆ signal_in_route

boost::signals2::signal<void(const protobuf::QueuedMessageMeta& meta, const google::protobuf::Message& data_msg, int modem_id)> goby::acomms::QueueManager::signal_in_route

Used by a router to intercept messages and requeue them if desired.

Definition at line 234 of file queue_manager.h.

◆ signal_out_route

boost::signals2::signal<void(protobuf::QueuedMessageMeta* meta, const google::protobuf::Message& data_msg, int modem_id)> goby::acomms::QueueManager::signal_out_route

Used by a router to change next-hop destination (in meta)

Definition at line 229 of file queue_manager.h.

◆ signal_queue_size_change

boost::signals2::signal<void(protobuf::QueueSize size)> goby::acomms::QueueManager::signal_queue_size_change

Signals when any queue changes size (message is popped or pushed)

"size": message containing the queue that changed size and its new size (protobuf::QueueSize is defined in queue.proto).

Definition at line 223 of file queue_manager.h.

◆ signal_receive

boost::signals2::signal<void(const google::protobuf::Message& msg)> goby::acomms::QueueManager::signal_receive

Signals when a DCCL message is received.

"msg": the received transmission.

Definition at line 205 of file queue_manager.h.

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

goby/acomms/queue/queue_manager.h

Public Member Functions

Application Signals

Detailed Description

Constructor & Destructor Documentation

◆ QueueManager()

◆ ~QueueManager()

Member Function Documentation

◆ add_queue() [1/2]

◆ add_queue() [2/2]

◆ do_work()

◆ flush_queue()

◆ glog_in_group()

◆ glog_out_group()

◆ glog_pop_group()

◆ glog_priority_group()

◆ glog_push_group()

◆ handle_modem_data_request()

◆ handle_modem_receive()

◆ info() [1/2]

◆ info() [2/2]

◆ info_all()

◆ merge_cfg()

◆ meta_from_msg()

◆ modem_id()

◆ msg_string()

◆ push_message() [1/2]

◆ push_message() [2/2]

◆ set_cfg()

Friends And Related Symbol Documentation

◆ Queue

Member Data Documentation

◆ signal_ack

◆ signal_data_on_demand

◆ signal_expire

◆ signal_in_route

◆ signal_out_route

◆ signal_queue_size_change

◆ signal_receive