goby::acomms::QueueManager Class Reference

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

#include <goby/acomms/queue.h>

List of all members.

Public Member Functions
Constructors/Destructor
	QueueManager (std::ostream *log=0)
	Default constructor.
	~QueueManager ()
	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 queue.proto)
void	merge_cfg (const protobuf::QueueManagerConfig &cfg)
	Set (and merge "repeat" fields) the current configuration. (protobuf::QueueManagerConfig defined in queue.proto)
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 protobuf::ModemDataTransmission &new_message)
	Push a message using a QueueKey as a key.
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 (const protobuf::ModemDataRequest &msg_request, protobuf::ModemDataTransmission *msg_data)
	Finds data to send to the modem.
void	handle_modem_receive (const protobuf::ModemDataTransmission &message)
	Receive incoming data from the modem.
void	handle_modem_ack (const protobuf::ModemDataAck &message)
	Receive acknowledgements 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
std::string	summary () const
const ManipulatorManager &	manip_manager () const
Static Public Member Functions
Static helpers
static void	add_flex_groups (util::FlexOstream *tout)
	Registers the group names used for the FlexOstream logger.
Public Attributes
Application Signals
boost::signal< void(const protobuf::ModemDataAck &ack_msg)>	signal_ack
	Signals when acknowledgment of proper message receipt has been received. This is only sent for queues with QueueConfig::ack() == true with an explicit destination (ModemMessageBase::dest() != 0)
boost::signal< void(const protobuf::ModemDataTransmission &msg)>	signal_receive
	Signals when a DCCL message is received.
boost::signal< void(const protobuf::ModemDataTransmission &msg)>	signal_receive_ccl
	Signals when a CCL message is received.
boost::signal< void(const protobuf::ModemDataExpire &expire_msg)>	signal_expire
	Signals when a message is expires (exceeds its time-to-live or ttl) before being sent (if QueueConfig::ack() == false) or before being acknowledged (if QueueConfig::ack() == true).
boost::signal< void(const protobuf::ModemDataRequest &request_msg, protobuf::ModemDataTransmission *data_msg)	signal_data_on_demand )
	Forwards the data request to the application layer. This advanced feature is used with the ON_DEMAND manipulator and allows for the application to provide data immediately before it is actually sent (for highly time sensitive data)
boost::signal< void(protobuf::QueueSize size)>	signal_queue_size_change
	Signals when any queue changes size (message is popped or pushed)
Friends
class	Queue

---

Detailed Description

provides an API to the goby-acomms Queuing Library.

See also:

queue.proto and modem_message.proto for definition of Google Protocol Buffers messages (namespace goby::acomms::protobuf).

Examples:

acomms/chat/chat.cpp, and libqueue/queue_simple/queue_simple.cpp.

Definition at line 54 of file queue_manager.h.

---

Constructor & Destructor Documentation

goby::acomms::QueueManager::QueueManager

(

std::ostream *

log = 0

)

Default constructor.

Parameters:

log	std::ostream object or FlexOstream to capture all humanly readable runtime and debug information (optional).

Definition at line 34 of file queue_manager.cpp.

---

Member Function Documentation

void goby::acomms::QueueManager::flush_queue

(

const protobuf::QueueFlush &

flush

)

Flush (delete all messages in) a queue.

Parameters:

QueueFlush

flush: object containing details about queues to flush

Definition at line 147 of file queue_manager.cpp.

void goby::acomms::QueueManager::handle_modem_ack

(

const protobuf::ModemDataAck &

message

)

Receive acknowledgements from the modem.

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

Parameters:

message

The ModemMessage corresponding to the acknowledgement (dest, src, frame#)

Definition at line 424 of file queue_manager.cpp.

void goby::acomms::QueueManager::handle_modem_data_request	(	const protobuf::ModemDataRequest &	msg_request,
		protobuf::ModemDataTransmission *	msg_data
	)

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 bound and passed to ModemDriverBase::set_datarequest_cb.

Parameters:

message_in	The ModemMessage containing the details of the request (source, destination, size, etc.)
message_out	The packed ModemMessage ready for sending by the modem. This will be populated by this function.

Returns:

true if successful in finding data to send, false if no data is available

Definition at line 188 of file queue_manager.cpp.

void goby::acomms::QueueManager::handle_modem_receive

(

const protobuf::ModemDataTransmission &

message

)

Receive incoming data from the modem.

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

Parameters:

message

The received ModemMessage.

Definition at line 482 of file queue_manager.cpp.

void goby::acomms::QueueManager::push_message

(

const protobuf::ModemDataTransmission &

new_message

)

Push a message using a QueueKey as a key.

Parameters:

key	QueueKey that references the queue to push the message to.
new_message	ModemMessage to push.

Definition at line 110 of file queue_manager.cpp.

std::string goby::acomms::QueueManager::summary

(

)

const

Returns:

human readable summary of all loaded queues

Definition at line 164 of file queue_manager.cpp.

---

Member Data Documentation

boost::signal<void (const protobuf::ModemDataAck& ack_msg)> goby::acomms::QueueManager::signal_ack

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

Parameters:

ack_msg

a message containing details of the acknowledgment and the acknowledged transmission. (protobuf::ModemMsgAck is defined in modem_message.proto)

Definition at line 163 of file queue_manager.h.

boost::signal<void (const protobuf::ModemDataRequest& request_msg, protobuf::ModemDataTransmission* data_msg) goby::acomms::QueueManager::signal_data_on_demand)

Forwards the data request to the application layer. This advanced feature is used with the ON_DEMAND manipulator and allows for the application to provide data immediately before it is actually sent (for highly time sensitive data)

Parameters:

request_msg	the details of the requested data. (protobuf::ModemDataRequest is defined in modem_message.proto)
data_msg	pointer to store the supplied data. (protobuf::ModemDataTransmission is defined in modem_message.proto)

Definition at line 184 of file queue_manager.h.

boost::signal<void (const protobuf::ModemDataExpire& expire_msg)> goby::acomms::QueueManager::signal_expire

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

Parameters:

expire_msg

the expired transmission. (protobuf::ModemDataExpire is defined in modem_message.proto)

Definition at line 177 of file queue_manager.h.

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

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

Parameters:

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

Definition at line 189 of file queue_manager.h.

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

Signals when a DCCL message is received.

Parameters:

msg	the received transmission. (protobuf::ModemDataTransmission is defined in modem_message.proto)

Definition at line 167 of file queue_manager.h.

boost::signal<void (const protobuf::ModemDataTransmission& msg)> goby::acomms::QueueManager::signal_receive_ccl

Signals when a CCL message is received.

Parameters:

msg	the received transmission. (protobuf::ModemDataTransmission is defined in modem_message.proto)

Definition at line 172 of file queue_manager.h.

---

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

• acomms/libqueue/queue_manager.h
• acomms/libqueue/queue_manager.cpp