Goby v2
Classes | Public Member Functions | Public Attributes | Friends | List of all members

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

#include <goby/acomms/queue.h>

Public Member Functions

 QueueManager ()
 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 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. More...
 
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) More...
 
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. More...
 
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. More...
 
void handle_modem_receive (const protobuf::ModemTransmission &message)
 Receive incoming data from the modem. More...
 
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. More...
 
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. More...
 
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)
 

Public Attributes

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.
 
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) More...
 
boost::signals2::signal< void(const google::protobuf::Message &msg)> signal_receive
 Signals when a DCCL message is received. More...
 
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). More...
 
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) More...
 
boost::signals2::signal< void(protobuf::QueueSize size)> signal_queue_size_change
 Signals when any queue changes size (message is popped or pushed) More...
 

Friends

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).
Examples:
acomms/chat/chat.cpp, and acomms/queue/queue_simple/queue_simple.cpp.

Definition at line 49 of file queue_manager.h.

Member Function Documentation

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
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)

Definition at line 72 of file queue_manager.h.

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

Flush (delete all messages in) a queue.

Parameters
flushQueueFlush object containing details about queue to flush

Definition at line 164 of file queue_manager.cpp.

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
msgThe ModemTransmission containing information about the data request and is the place where the request data will be stored (in the repeated field ModemTransmission::frame).
Returns
true if successful in finding data to send, false if no data is available
Examples:
acomms/queue/queue_simple/queue_simple.cpp.

Definition at line 220 of file queue_manager.cpp.

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
messageThe received ModemMessage.
Examples:
acomms/queue/queue_simple/queue_simple.cpp.

Definition at line 648 of file queue_manager.cpp.

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
ProtobufMessageAny Google Protobuf Message generated by protoc (i.e. subclass of google::protobuf::Message)
Parameters
osPointer to a stream to write this information

Definition at line 142 of file queue_manager.h.

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

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

Parameters
osPointer to a stream to write this information

Definition at line 182 of file queue_manager.cpp.

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_messageDCCL message to push.
Examples:
acomms/chat/chat.cpp, and acomms/queue/queue_simple/queue_simple.cpp.

Definition at line 137 of file queue_manager.cpp.

Member Data Documentation

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)

Parameters
ack_msga message containing details of the acknowledgment and the acknowledged transmission. (protobuf::ModemMsgAck is defined in acomms_modem_message.proto)
Examples:
acomms/chat/chat.cpp.

Definition at line 183 of file queue_manager.h.

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)

Parameters
request_msgthe details of the requested data. (protobuf::ModemDataRequest is defined in acomms_modem_message.proto)
data_msgpointer to store the supplied data. The message is of the type for this queue.

Definition at line 201 of file queue_manager.h.

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

Parameters
expire_msgthe expired transmission. (protobuf::ModemDataExpire is defined in acomms_modem_message.proto)

Definition at line 193 of file queue_manager.h.

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)

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

Definition at line 206 of file queue_manager.h.

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

Signals when a DCCL message is received.

Parameters
msgthe received transmission.
Examples:
acomms/chat/chat.cpp, and acomms/queue/queue_simple/queue_simple.cpp.

Definition at line 188 of file queue_manager.h.


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