Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Related Pages

s3_message_box Class Reference

An implementation of a Message box. More...

#include <s3_message.h>

Collaboration diagram for s3_message_box:

Public Types
typedef std::list< s3_message >	T_RX_Queue
Public Methods
	s3_message_box (const std::string &name="", unsigned int n_queue_len=20)
	Construct a new message box instance with specified `name` and `rx_queue` length. More...
	~s3_message_box ()
	Disconnect message box from post office. More...
void	set_name (const std::string &name)
	Set the name of this `s3_message_client` instance. More...
void	connect ()
	Connect to and register with the post office. More...
void	disconnect ()
	Disconnect and unregister from the post_office. More...
void	subscribe_group (const std::string &group)
	Subscribe this message box to the specified group. More...
void	unsubscribe_group (const std::string &group)
	Unsubscribe this message box from the specified group. More...
void	subscribe_arrival (const s3_semaphore &sem)
	Subscribe the supplied semaphore to the arrival notification list. More...
s3_message::msg_id_t	send_msg (const std::string &dst, const std::string &body, bool priority=false)
	Send a message to the specified destination. More...
s3_message::msg_id_t	reply_msg (const s3_message &msg, const std::string &body="")
	Send a reply message. More...
s3_message	get_msg ()
	Retrieve and remove the candidate message from the queue. More...
Static Public Methods
void	init (const std::string &ip_addr, int port)
	Initialise the postal system. More...
void	de_init ()
	De-initialise the postal system - stop the post office active in the current process space. More...
bool	initialised ()
	Return the initialisation status. More...
Static Public Attributes
unsigned int	dropped_msg_count = 0
	This counter keeps track of how many messages have been dropped in this process space. More...
Protected Methods
void	deliver_msg (const s3_message &msg)
	Add a message into the queue. More...
std::string	err_str (const std::string &err)
	Return an error string containing the message box name. More...
std::string	get_next_message_id ()
	Return the next message id in the sequence. More...
Private Attributes
bool	connected
	Flag indicating whether a connection to a post office exists. More...
std::string	name
	Name of this message box. More...
unsigned int	rx_queue_len
	Queue lengths (RX and TX). More...
T_RX_Queue	rx_queue
	RX queue - finite length is implemented in deliver_msg. More...
std::list< std::string >	subscription_list
	Group subscription list. More...
int	seq_nr
	Sequence count used to generate message IDs. More...
std::list< s3_semaphore * >	arrival_notification_list
	Everybody in list is notified if message is received. More...
s3_mutex	state_lock
	Global lock ensures state consistency. More...
Static Private Attributes
s3_post_office *	poffice = 0
	Post office instance - the post office that we use. More...
Friends
class	s3_post_office

Detailed Description

An implementation of a Message box.

name is implemented as a string. The rx_queue is implemented by an STL list containing s3_message objects. An internal parameter contains the maximum size that the list may attain. s3_post_office is declared as a friend class, in order to make use of the delivery mechanism. Each sent message is tagged with a message ID, that is a string consisting of the name of the message_box and a sequence number. This ID should be used in calls to s3_message::is_reply().

@note: This implementation is not intended to be used as a communication endpoint by more than one thread at the same time.

See also:: Postal System

Definition at line 513 of file s3_message.h.

Member Typedef Documentation

typedef std::list<s3_message> s3_message_box::T_RX_Queue

Definition at line 518 of file s3_message.h.

Constructor & Destructor Documentation

s3_message_box::s3_message_box ( const std::string & name = "",

unsigned int n_queue_len = 20

)

Construct a new message box instance with specified name and rx_queue length.

Parameters:

n_name Name (optional - default: "")

n_rx_queue_len rx_queue length (optional - default: 20)

Definition at line 203 of file s3_message.cc.

s3_message_box::~s3_message_box ( )

Disconnect message box from post office.

Definition at line 215 of file s3_message.cc.
References disconnect.

Member Function Documentation

void s3_message_box::connect ( )

Connect to and register with the post office.
Throw an s3_generic_exception if any of the following errors occur:

The message box is already connected.
The message box has an invalid name.
A message box of the same name is already registered in the postal system.
The post office is not connected to a post office switch

Definition at line 292 of file s3_message.cc.
References s3_post_office::add_dst, connected, err_str, name, and poffice.
Referenced by s3_msgb_log_buffer::s3_msgb_log_buffer, s3_msgb_log_rx_thread::s3_msgb_log_rx_thread, s3_rpc_client::s3_rpc_client, and s3_rpc_server::s3_rpc_server.

void s3_message_box::de_init ( ) [static]

De-initialise the postal system - stop the post office active in the current process space.

Postcondition:
initialised() == false

Definition at line 254 of file s3_message.cc.
References s3_post_office::disconnect, initialised, poffice, s3_thread_base::request_terminate, and s3_thread_base::wait_on_exit.

void s3_message_box::deliver_msg ( const s3_message & msg ) [protected]

Add a message into the queue.
If the message queue is full, the oldest non-priority message is removed, unless there are only priority messages in the queue, in which case it removes the oldest priority message.
Definition at line 451 of file s3_message.cc.
References arrival_notification_list, dropped_msg_count, s3_message::get_class, s3_mutex::lock, s3_message::NORMAL, s3_message::PRIORITY, rx_queue, rx_queue_len, state_lock, and s3_mutex::unlock.

void s3_message_box::disconnect ( )

Disconnect and unregister from the post_office.
Throw an s3_generic_exception if the message box is not connected.
Definition at line 312 of file s3_message.cc.
References connected, err_str, name, poffice, s3_post_office::remove_dst, subscription_list, and unsubscribe_group.
Referenced by ~s3_message_box, s3_msgb_log_buffer::~s3_msgb_log_buffer, s3_msgb_log_rx_thread::~s3_msgb_log_rx_thread, s3_rpc_client::~s3_rpc_client, and s3_rpc_server::~s3_rpc_server.

std::string s3_message_box::err_str ( const std::string & err ) [protected]

Return an error string containing the message box name.

Definition at line 529 of file s3_message.cc.
References name.
Referenced by connect, disconnect, send_msg, set_name, subscribe_arrival, subscribe_group, and unsubscribe_group.

s3_message s3_message_box::get_msg ( )

Retrieve and remove the candidate message from the queue.
If there are no messages in the queue, an empty message is returned.
Definition at line 427 of file s3_message.cc.
References s3_mutex::lock, rx_queue, state_lock, and s3_mutex::unlock.
Referenced by s3_rpc_server::main_loop, and s3_msgb_log_rx_thread::main_loop.

std::string s3_message_box::get_next_message_id ( ) [protected]

Return the next message id in the sequence.

Definition at line 538 of file s3_message.cc.
References name, and seq_nr.
Referenced by reply_msg, and send_msg.

void s3_message_box::init ( const std::string & ip_addr,

int port

) [static]

Initialise the postal system.
This should be called exactly once in every process space, before any message boxes is instantiated.
Parameters:

ip_addr IP address of switch.

port Port at which switch is listening.

Precondition:
initialised() == false
Postcondition:
poffice contains a valid and running post office instance.
initialised() == true

Definition at line 225 of file s3_message.cc.
References s3_post_office::connect, initialised, poffice, and s3_post_office.
Referenced by s3_msgb_log_buffer::s3_msgb_log_buffer, and s3_msgb_log_rx_thread::s3_msgb_log_rx_thread.

bool s3_message_box::initialised ( ) [static]

Return the initialisation status.
The status is true if the postal system has been initialised in the calling process space.
Definition at line 271 of file s3_message.cc.
References s3_post_office::is_connected, poffice, and S3FC_DBG.
Referenced by de_init, init, s3_msgb_log_buffer::s3_msgb_log_buffer, and s3_msgb_log_rx_thread::s3_msgb_log_rx_thread.

s3_message::msg_id_t s3_message_box::reply_msg ( const s3_message & msg,

const std::string & body = ""

)

Send a reply message.
This is similar to sending an ordinary message, except that the destination address and priority are taken from msg. The new message has a reply_id equal to the id field of msg. The priority is the same as that of msg and the destination address is the originating address of msg ( msg.get_to() ). This call returns the message ID of the newly created message and replies can therefore also be sent to this message. If the message body argument, body, is omitted an empty string is assumed by default. This is used to generate simple acknowledge messages.
Parameters:

msg Message to reply to.

body Message body (optional - default: "")

Returns:
ID of the new message.

Definition at line 415 of file s3_message.cc.
References s3_post_office::dispatch_msg, get_next_message_id, s3_message::msg_id_t, name, and poffice.
Referenced by s3_rpc_server::reply_client.

s3_message::msg_id_t s3_message_box::send_msg ( const std::string & dst,

const std::string & body,

bool priority = false

)

Send a message to the specified destination.
A priority message is sent if the priority flag is set.
Parameters:

dst Destination.

body Message body.

priority Priority flag.

Returns:
ID of the new message.

Definition at line 396 of file s3_message.cc.
References connected, s3_post_office::dispatch_msg, err_str, get_next_message_id, s3_message::msg_id_t, name, s3_message::NORMAL, poffice, and s3_message::PRIORITY.
Referenced by s3_rpc_client::call_common, and s3_msgb_log_buffer::write_to_device.

void s3_message_box::set_name ( const std::string & name )

Set the name of this s3_message_client instance.
Throw an s3_generic_exception if the message box is connected.
Note:
A message name may only contain alphanumeric characters and underscor, i.e. [ A-Z, 0-9, '_' ]
Parameters:

n_name Name

Definition at line 281 of file s3_message.cc.
References err_str, and name.
Referenced by s3_msgb_log_buffer::s3_msgb_log_buffer, s3_rpc_client::s3_rpc_client, and s3_rpc_server::s3_rpc_server.

void s3_message_box::subscribe_arrival ( const s3_semaphore & sem )

Subscribe the supplied semaphore to the arrival notification list.

Parameters:

sem A semaphore that would be used to indicate that a new message has arrived (using post() ). The caller should ensure that the semaphore stays valid throughuot the existence of this instance.

Precondition:
The semaphore has not been previously subscribed: throw s3_generic_exception when violated.

Definition at line 379 of file s3_message.cc.
References arrival_notification_list, and err_str.
Referenced by s3_rpc_server::main_loop, and s3_msgb_log_rx_thread::s3_msgb_log_rx_thread.

void s3_message_box::subscribe_group ( const std::string & group )

Subscribe this message box to the specified group.
Throw an s3_generic_exception if any of the following errors occur:

The message box is not connected.
The group name clashes with the name of a message box.

Parameters:

group Group name.

Definition at line 331 of file s3_message.cc.
References s3_post_office::add_dst, connected, err_str, poffice, and subscription_list.

void s3_message_box::unsubscribe_group ( const std::string & group )

Unsubscribe this message box from the specified group.
Throw an s3_generic_exception if any of the following errors occur:

The message box is not connected.
This message box is not subscribed to the specified group.

Parameters:

group Group name.

Definition at line 356 of file s3_message.cc.
References connected, err_str, poffice, s3_post_office::remove_dst, and subscription_list.
Referenced by disconnect.

Friends And Related Function Documentation

friend class s3_post_office [friend]

Definition at line 516 of file s3_message.h.
Referenced by init.

Member Data Documentation

std::list<s3_semaphore*> s3_message_box::arrival_notification_list [private]

Everybody in list is notified if message is received.

Definition at line 559 of file s3_message.h.
Referenced by deliver_msg, and subscribe_arrival.

bool s3_message_box::connected [private]

Flag indicating whether a connection to a post office exists.

Definition at line 535 of file s3_message.h.
Referenced by connect, disconnect, send_msg, subscribe_group, and unsubscribe_group.

unsigned int s3_message_box::dropped_msg_count = 0 [static]

This counter keeps track of how many messages have been dropped in this process space.

Definition at line 200 of file s3_message.cc.
Referenced by deliver_msg.

std::string s3_message_box::name [private]

Name of this message box.

Definition at line 539 of file s3_message.h.
Referenced by connect, disconnect, err_str, get_next_message_id, reply_msg, send_msg, and set_name.

s3_post_office * s3_message_box::poffice = 0 [static, private]

Post office instance - the post office that we use.
All messages boxes in a process space share the post office, so we set this to point to a global instance. The post office is created by init()
Definition at line 199 of file s3_message.cc.
Referenced by connect, de_init, disconnect, init, initialised, reply_msg, send_msg, subscribe_group, and unsubscribe_group.

T_RX_Queue s3_message_box::rx_queue [private]

RX queue - finite length is implemented in deliver_msg.

Definition at line 547 of file s3_message.h.
Referenced by deliver_msg, and get_msg.

unsigned int s3_message_box::rx_queue_len [private]

Queue lengths (RX and TX).

Definition at line 543 of file s3_message.h.
Referenced by deliver_msg.

int s3_message_box::seq_nr [private]

Sequence count used to generate message IDs.

Definition at line 555 of file s3_message.h.
Referenced by get_next_message_id.

s3_mutex s3_message_box::state_lock [private]

Global lock ensures state consistency.

Definition at line 563 of file s3_message.h.
Referenced by deliver_msg, and get_msg.

std::list<std::string> s3_message_box::subscription_list [private]

Group subscription list.

Definition at line 551 of file s3_message.h.
Referenced by disconnect, subscribe_group, and unsubscribe_group.

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

Send comments to: s3fc@stonethree.com

s3_message_box Class Reference

Public Types

Public Methods

Static Public Methods

Static Public Attributes

Protected Methods

Private Attributes