Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members File Members Related Pages
Postal System
This documents the S3FC Postal System and all its components. The postal system allows an application programmer to send text messages between a number of named nodes.
Components
The postal system consists of the following components:
- Message: Information-carrying packets that traverse the postal system. [ s3_message ]
- Message box: A communication endpoint. An application programmer uses this as a communication endpoint to send messages destined for other message boxes and retrieves messages that was sent from other message boxes. [ s3_message_box ]
- Post Office: Each message box connects to a post office and uses it to send and receive messages. A post office and a message box that is connected to it, has to be in the same process space. [ s3_post_office ]
- Post Office Switch: Post offices in different process spaces connect to each other through a post office switch. [ s3_post_office_switch ]
A number of message boxes, connected to a number of post offices that are in turn all connected to the same post office switch, constitutes a single postal system.
Overall operation
The following rules describe the operation of a postal system:
- Each message box has a name (text string), that is unique within the postal system, that is used to address it.
- Message boxes can be subscribed to one or more groups, also identified by a name (a text string).
- The union of all message box names and subscribed groups in a single postal system comprise a number of destinations.
- A destination should be either an individual message box or a group.
- A message box receives all messages addressed directly to it (by name), or addressed to a group to which it has subscribed.
- A message can be sent from any message box to any other message box or group connected to the same postal system.
- Communication is connection-based, i.e. a message box has to connect to a post office and register itself with it in order to be able to send and receive messages on a postal system. A post office has to connect to a post office switch.
- Post offices address a post office switch using its internet address (IP:port). Only a single post office switch can be present at a single internet address.
Message
[ s3_message ]
Attributes:
- empty: A boolean attibute indicating whether a message is empty or not. All other attributes of an empty message should be ignored.
- from: The address of the originator: a text string.
- to: The address of the destination: a text string.
- body: The actual message: a text string.
- class: Discriminates special messages from ordinary. The following are defined:
- NORMAL: A regular message.
- PRIORITY: A priority message.
- CONTROL: A control message.
- id: An ID that is used to track a message for purposes of delivery verification and acknowledgement. Each message has a unique ID.
- reply_id: The ID of the message that this message replies to (if it is a reply message).
Operations:
- is_empty: Return a value indicating whether this is an empty message. Empty messages are used to signify that no message is available in cases that require a message to be returned.
- is_reply: Return a value indicating whether this is a reply on a message with a specified tracking id.
Message box
[ s3_message_box ]
Attributes:
- name: A text string used to identify this instance (as a destination).
- rx_queue: A finite-length queue containing all received messages.
- subscription_list: A list of groups to which this message box is subscribed.
- arrival_notification_list: A list of semaphores that is used to signal the arrival of a message. Each semaphore in the list is
post 'ed each time a new message arrives. This allows asynchronous message handling without busy waiting.
Operations:
- connect: Register this message box with a post office.
- disconnect: Unregister this message box from a post office.
- subscribe_group: Subscribe this message box to a group using the
add_dst operation of Post Office. Add the group name to the subscription_list. This fails if it is already subscribed to the group. - unsubscribe_group: Unsubscribe this message box from a group using the
remove_dst operation of Post Office. Remove the group name from the subscription_list. This fails if it is not subscribed to the group. - subscribe_arrival: Add a semaphore, to be used for new message notification, to the
arrival_notification_list. This fails if the semaphore is already in the list. - send_msg: Create a normal or priority message addressed to a specified destination, dispatch it to the Post Office and return a message ID. The message ID is used to acknowledge reception, from the receiver(s).
- reply_msg: Create and send a message in reply to a received message. An empty reply message is used to acknowledge delivery (which is checked at the original sender's side using
is_reply). The message is created as follows:
- The from address of the received message is used as the destination address.
- The priority of the received message is used.
- The body is a specified string.
- The created message is created as a reply to the received message.
- get_msg: Retrieve and remove the next candidate message from the
rx_queue. The next candidate is the oldest message in the queue, unless there are priority messages in the queue, in which case the candidate is the oldest priority message. Age is determnined by arrival time. An empty message is returned if the rc_queue is empty. - deliver_msg: Deliver a message into the
rx_queue. As the rx_queue has a finite length, it can happen that a message is delivered while the queue is full. In this case, the policy is to remove the oldest message from the list, in favour of the new message. Normal messages are removed in favour of priority messages. Each semaphore in the arrival_notification_list is post 'ed.
Post Office
[ s3_post_office ]
Attributes:
- destination_map: A mapping from a destination address to a list of client instances (client_list) and a destination type (whether it is a group or not).
- client_rx_queue: A queue containing all messages received from clients, along with the client that dispatched it.
- ctrl_rx_queue: A queue containing all control messages that are received from the switch.
- switch_ip: The IP address of the Post Office Switch.
- switch_port: The listening port of the Post Office Switch
Operations:
- add_dst: Add a mapping from a destination (with specified type) to a client. The following steps are followed:
- If the post office is not connected, the operation fails.
- If the destination is not a group and it is already in the map, the operation fails.
- If the destination is not present in the
dst_map, the request is forwarded to the Post Office Switch and the name registered and checked for uniqueness. If this succeeds, it is added into the destination map, if it fails, the operation fails. - Else, the client is added to the client list of the destination (in the. map).
- remove_dst: Remove the mapping between a destination and a client:
- If the post office is not connected, the operation fails.
- If the destination is not in the map, the operation fails.
- If there is only a single client in the client_list associated with the client, remove the destination from the map and forward the request to the Post Office Switch.
- Else the client is removed from the client list associated with the destination.
- connect: Establish a connection with the post office switch. This should be done before any clients connect.
- disconnect: Disconnect from the post office switch. This should only be attempted after all clients have unregistered (i.e. the destination_map should be empty).
- dispatch_msg: Dispatch a message (used by a client to send a message). This fails if the post office is not connected to a Post Office Switch.
Messages that in the rx_queue are retrieved and routed. The following rules determine the fate of the message:
- The message is a control message: push it into the
ctrl_rx_queue. - The message arrives from the switch and the destination is present in the destination map: forward it to all clients that are in the client list of the destination.
- The message arrives from a client and the destination is not present in the destination map: forward it to the switch.
- The message arrives from a client and the destination is present in the destination map and the destination type is not group: forward it to the (single) client in the client list of the destination.
- The message arrives from a client and the destination is present in the destination map and the destination type is group: forward it to the clients in the client list of the destination and forward it to the switch. If none of the above rules intercept and handle the message, it is simply dropped (ignored).
The post office connects to the post office switch using TCP/IP. It therefore requires knowledge of the IP address and listening port of the post office switch.
Post Office Switch
[ s3_post_office_switch ]
Attributes:
- destination_map: A mapping from the destination address to a list of the Post Office connections (
client_connection list) and a destination type.
Operations:
- add_dst: Add a mapping from a destination to a connection and a destination type. If the destination already exists, and is not a group destination, this operation fails. If the destination already exists, and it is a group destination, the connection is added onto the client_connection list for that destination. Otherwise, a new destination entry is created in the map and the connection is added into the client_connection list.
- remove_dst: Remove a mapping between a destination and a connection. If this leaves the
client_connection list empty, the destination is removed from the map.
The switch accepts network connections from any number of Post Office instances. All post offices at any moment connected to a switch comprise the postal system at that moment. The switch receives packets containing messages from the connected post office instances and distributes them over the postal system. If a client connection is lost, that connection is removed from all client connection_lists in the map. If this leaves a list empty, the destination is removed from the map. Messages are routed acco rding to the following rules:
- Any received message is forwarded to all connections in the connection list of that destination, except the one on which it was received.
As the post office switch and the post office never share a process space, control messages (messages with the type set to CONTROL are used to implement the add_dst and remove_dst operations. The message body has the following format:
operation type destination
operation indicates the operation and is one of the following strings:
type indicates the destination type and is one of the folllowing:
destination indicates the destination address and contains the name of the message box instance that is registering the name or the name of the group that is being subscribed to.
A response control message is sent (with the from and to addresses exchanged) on the same connection that the message was received. It either contains the string failure or success, indicating whether the request failed or succeeded.