s3_post_office Class Reference

A Post Office implementation. More...

#include <s3_message.h>

Inheritance diagram for s3_post_office:

[legend]Collaboration diagram for s3_post_office:

[legend]List of all members.

Public Methods
	~s3_post_office ()
	The destructor, cleans up the conn now. More...
	s3_post_office ()
	Instantiate a post office. More...
void	connect (const std::string &ip, int port)
	Connect to the post office switch listening at the specified port and IP address. More...
void	disconnect ()
	Disconnect from the post office switch. More...
void	add_dst (const std::string &dst, s3_message_box &mbox, bool is_group)
	Associate the destination address `dst` with the client `mbox` and the specified destination type. More...
void	remove_dst (const std::string &dst, s3_message_box &mbox, bool is_group)
	Remove the association between destination address `dst` and the client `mbox`. More...
virtual void	main_loop ()
	Read the demultiplex all messages that arrive from the switch (i.e. More...
Protected Methods
void	dispatch_msg (const s3_message &msg, s3_message_box &mbox)
	Accept a message from an `s3_message_box` and enqueue it for distribution. More...
bool	is_connected () const
	Return the connection status. More...
bool	add_dst_switch (const std::string &name, bool is_group)
	Send a request to the switch to add an association between the specified destination name and this instance. More...
bool	remove_dst_switch (const std::string &name, bool is_group)
	Send a request to the switch to remove the association between the specified name and the connection to this instance. More...
void	deliver_all_but_one (const s3_message &msg, const std::list< s3_message_box * > &clients, const s3_message_box *except)
	Deliver a message to all clients except one. More...
std::string	get_next_message_id ()
	Return the next message id in the sequence. More...
Private Attributes
s3_txport_tcp< s3_message > *	conn
	Physical (TCP/IP) connection endpoint. More...
s3_txport_client_id	conn_id
	Connection ID of the connection to the Post Office Switch. More...
std::map< std::string, dst_data >	dst_map
	The destination map: destination name to client list and destination type. More...
s3_fifo_queue< s3_message >	ctrl_rx_queue
	Control RX queue - all received control messages end up here. More...
s3_fifo_queue< client_msg >	client_rx_queue
	Queue containing messages dispatched by clients. More...
int	seq_nr
	Sequence count used to generate message IDs. More...
s3_mutex	dst_lock
	Lock that guards entire critical sections of operations that add or remove destinations. More...
s3_semaphore	started
	Semaphore used to synchronise startup. More...
Friends
class	s3_message_box

Detailed Description

A Post Office implementation.

Each instance executes as a thread with a main event loop that sevices the client connections and the connection to the Post Office Switch. The destination map is implemented as an STL map from string (destination address) to dst_data (structure containing an STL list of s3_message_box* and a bool indicating whether it is a group address. The physical connection between a s3_post_office and a Post Office Switch implementation, s3_post_office_switch, is accomplished using a s3_txport_tcp<s3_message>, operating as a client (i.e. connected), in the s3_post_office.

See also:: Postal System

Definition at line 712 of file s3_message.h.

Constructor & Destructor Documentation

s3_post_office::~s3_post_office ( )

The destructor, cleans up the conn now.

Definition at line 556 of file s3_message.cc.
References disconnect, and is_connected.

s3_post_office::s3_post_office ( )

Instantiate a post office.

Definition at line 547 of file s3_message.cc.

Member Function Documentation

void s3_post_office::add_dst ( const std::string & dst,

s3_message_box & mbox,

bool is_group

)

Associate the destination address dst with the client mbox and the specified destination type.

Definition at line 653 of file s3_message.cc.
References add_dst_switch, dst_lock, dst_map, is_connected, s3_mutex::lock, s3_thread_base::lock_state, s3_mutex::unlock, and s3_thread_base::unlock_state.
Referenced by s3_message_box::connect, and s3_message_box::subscribe_group.

bool s3_post_office::add_dst_switch ( const std::string & name,

bool is_group

) [protected]

Send a request to the switch to add an association between the specified destination name and this instance.
The name is checked for uniqueness if is not a group name. The operation fails if a name clash is detected. This uses the add_dst operation of the switch.
Parameters:

name Destination name.

is_group Flag indicating whether the address belongs to a group.

Returns:
Value indicating whether the operation succeeded.
Note:
No other thread may access the control queue while this operation is in progress.

Definition at line 979 of file s3_message.cc.
References conn, conn_id, s3_message::CONTROL, ctrl_rx_queue, s3_message::get_body, s3_message::get_debug_str, get_next_message_id, s3_txport_tcp< s3_message >::get_tx_queue, s3_inplace_fifo_base< s3_message >::pop, and S3FC_DBG.
Referenced by add_dst.

void s3_post_office::connect ( const std::string & ip,

int port

)

Connect to the post office switch listening at the specified port and IP address.
If the connection succeeds, the main event loop is started. This call only returns after successful startup, i.e. when the event loop is running. This throws an s3_generic_exception if any of the following errors occur:

The post office is already connected to a post office switch.
The connection to the post office switch failed.

Parameters:

ip IP Address of a listening s3_post_office_switch instance.

port Port at which the s3_post_office_switch is listening.

Definition at line 599 of file s3_message.cc.
References conn, conn_id, s3_txport_tcp< s3_message >::connect, s3_txport_tcp< s3_message >::is_connected_by_id, s3_thread_base::start, started, and s3_semaphore::wait.
Referenced by s3_message_box::init.

void s3_post_office::deliver_all_but_one ( const s3_message & msg,

const std::list< s3_message_box * > & clients,

const s3_message_box * except

) [protected]

Deliver a message to all clients except one.

Parameters:

msg Message

clients Client list

except The excepted one

Definition at line 1035 of file s3_message.cc.
References S3FC_DBG.
Referenced by main_loop.

void s3_post_office::disconnect ( )

Disconnect from the post office switch.
Fail if any clients are still registered. The main event loop is stopped and the connection to the s3_post_office_switch is severed.
Definition at line 627 of file s3_message.cc.
References conn, dst_map, s3_txport_tcp< s3_message >::stop, and s3_thread_base::wait_on_exit.
Referenced by s3_message_box::de_init, and ~s3_post_office.

void s3_post_office::dispatch_msg ( const s3_message & msg,

s3_message_box & mbox

) [protected]

Accept a message from an s3_message_box and enqueue it for distribution.

Parameters:

msg Message

mbox Originating message box

Definition at line 965 of file s3_message.cc.
References client_rx_queue, and s3_inplace_fifo_base< client_msg >::push.
Referenced by s3_message_box::reply_msg, and s3_message_box::send_msg.

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

Return the next message id in the sequence.

Definition at line 1056 of file s3_message.cc.
References seq_nr.
Referenced by add_dst_switch, and remove_dst_switch.

bool s3_post_office::is_connected ( ) const [protected]

Return the connection status.

Return values:

c true Connected.

c true Disconnected.

Definition at line 972 of file s3_message.cc.
References conn, conn_id, and s3_txport_tcp< s3_message >::is_connected_by_id.
Referenced by add_dst, s3_message_box::initialised, main_loop, remove_dst, and ~s3_post_office.

void s3_post_office::main_loop ( ) [virtual]

Read the demultiplex all messages that arrive from the switch (i.e.
over the network). Ordinary messages are delivered according to the destination map. Control messages are enqueued into the control queue.
Implements s3_thread_base.
Definition at line 754 of file s3_message.cc.
References client_rx_queue, conn, conn_id, s3_message::CONTROL, ctrl_rx_queue, deliver_all_but_one, s3_periodic_notifier::disable, dst_map, s3_fifo_queue< client_msg >::empty, s3_fifo_queue::empty, s3_periodic_notifier::enable, s3_txport_tcp< s3_message >::get_rx_queue, s3_txport_tcp< s3_message >::get_tx_queue, is_connected, s3_thread_base::lock_state, s3_inplace_fifo_base< client_msg >::pop, s3_inplace_fifo_base::pop, s3_semaphore::post, s3_inplace_fifo_base::push, s3_inplace_fifo_base< s3_message >::push, S3FC_DBG, started, s3_periodic_notifier::subscribe, s3_subscribable_fifo::subscribe_consumer, s3_thread_base::test_terminate, s3_thread_base::unlock_state, s3_periodic_notifier::unsubscribe, and s3_semaphore::wait.

void s3_post_office::remove_dst ( const std::string & dst,

s3_message_box & mbox,

bool is_group

)

Remove the association between destination address dst and the client mbox.

Definition at line 707 of file s3_message.cc.
References dst_lock, dst_map, is_connected, s3_mutex::lock, s3_thread_base::lock_state, remove_dst_switch, s3_mutex::unlock, and s3_thread_base::unlock_state.
Referenced by s3_message_box::disconnect, and s3_message_box::unsubscribe_group.

bool s3_post_office::remove_dst_switch ( const std::string & name,

bool is_group

) [protected]

Send a request to the switch to remove the association between the specified name and the connection to this instance.
This uses the remove_dst operation of the switch.
Parameters:

name Destination name.

is_group Flag indicating whether the address belongs to a group. This is used to provide extra checking,

Returns:
Value indicating whether the operation succeeded.
Note:
No other thread may access the control queue while this operation is in progress.

Definition at line 1008 of file s3_message.cc.
References conn, conn_id, s3_message::CONTROL, ctrl_rx_queue, s3_message::get_body, s3_message::get_debug_str, get_next_message_id, s3_txport_tcp< s3_message >::get_tx_queue, s3_inplace_fifo_base< s3_message >::pop, and S3FC_DBG.
Referenced by remove_dst.

Friends And Related Function Documentation

friend class s3_message_box [friend]

Definition at line 714 of file s3_message.h.

Member Data Documentation

s3_fifo_queue<client_msg> s3_post_office::client_rx_queue [private]

Queue containing messages dispatched by clients.

Definition at line 774 of file s3_message.h.
Referenced by dispatch_msg, and main_loop.

s3_txport_tcp<s3_message>* s3_post_office::conn [private]

Physical (TCP/IP) connection endpoint.

Definition at line 754 of file s3_message.h.
Referenced by add_dst_switch, connect, disconnect, is_connected, main_loop, and remove_dst_switch.

s3_txport_client_id s3_post_office::conn_id [private]

Connection ID of the connection to the Post Office Switch.

Definition at line 760 of file s3_message.h.
Referenced by add_dst_switch, connect, is_connected, main_loop, and remove_dst_switch.

s3_fifo_queue<s3_message> s3_post_office::ctrl_rx_queue [private]

Control RX queue - all received control messages end up here.
It is a free-for-all queue that can be accessed by all member functions.
Definition at line 770 of file s3_message.h.
Referenced by add_dst_switch, main_loop, and remove_dst_switch.

s3_mutex s3_post_office::dst_lock [private]

Lock that guards entire critical sections of operations that add or remove destinations.
This does not lock the dst_map as such, but an entire operation possibly involving many dst_map reads and writes and control message dispatches. Any map manipulations may only be performed with this lock in place (in addition to the state_lock).
Definition at line 786 of file s3_message.h.
Referenced by add_dst, and remove_dst.

std::map<std::string, dst_data> s3_post_office::dst_map [private]

The destination map: destination name to client list and destination type.

Definition at line 765 of file s3_message.h.
Referenced by add_dst, disconnect, main_loop, and remove_dst.

int s3_post_office::seq_nr [private]

Sequence count used to generate message IDs.

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

s3_semaphore s3_post_office::started [private]

Semaphore used to synchronise startup.

Reimplemented from s3_thread_base.
Definition at line 790 of file s3_message.h.
Referenced by connect, and main_loop.

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

Send comments to: s3fc@stonethree.com

s3_post_office Class Reference

Public Methods

Protected Methods

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation