hamcast  Version 0.7
Classes | Typedefs | Enumerations | Functions
Inter-process communication.

Classes

class  hamcast::ipc::client_channel
 
class  hamcast::ipc::message
 
class  hamcast::ipc::message_view
 
struct  hamcast::ipc::sync_request_view
 
struct  hamcast::ipc::sync_response_view
 
struct  hamcast::ipc::async_send_view
 
struct  hamcast::ipc::async_recv_view
 
struct  hamcast::ipc::cumulative_ack_view
 
struct  hamcast::ipc::retransmit_view
 
class  hamcast::ipc::middleware_configuration
 

Typedefs

typedef boost::uint32_t hamcast::ipc::request_id
 
typedef boost::uint32_t hamcast::ipc::sequence_number
 
typedef boost::uint16_t hamcast::ipc::stream_id
 

Enumerations

enum  hamcast::ipc::exception_id {
  hamcast::ipc::eid_none = 0x0000,
  hamcast::ipc::eid_requirement_failed = 0x0001,
  hamcast::ipc::eid_internal_interface_error = 0x0002
}
 
enum  hamcast::ipc::function_id {
  hamcast::ipc::fid_create_socket = 0x0001,
  hamcast::ipc::fid_delete_socket = 0x0002,
  hamcast::ipc::fid_create_send_stream = 0x0003
}
 
enum  hamcast::ipc::message_type {
  hamcast::ipc::sync_request = 0x00,
  hamcast::ipc::sync_response = 0x01,
  hamcast::ipc::async_event = 0x02,
  hamcast::ipc::async_send = 0x03,
  hamcast::ipc::async_recv = 0x04,
  hamcast::ipc::cumulative_ack = 0x05,
  hamcast::ipc::retransmit = 0x06
}
 

Functions

socket_id hamcast::ipc::create_socket ()
 
void hamcast::ipc::delete_socket (socket_id sid)
 
stream_id hamcast::ipc::create_send_stream (socket_id sid, const uri &group)
 
void hamcast::ipc::join (socket_id sid, const uri &group)
 
void hamcast::ipc::leave (socket_id sid, const uri &group)
 
void hamcast::ipc::set_ttl (socket_id sid, boost::uint8_t value)
 
std::vector< interface_id > hamcast::ipc::get_sock_interfaces (socket_id sid)
 
void hamcast::ipc::add_sock_interface (socket_id sid, interface_id iid)
 
void hamcast::ipc::del_sock_interface (socket_id sid, interface_id iid)
 
void hamcast::ipc::set_sock_interfaces (socket_id sid, const std::vector< interface_id > &ifs)
 
std::vector< interface_property > hamcast::ipc::get_interfaces ()
 
std::vector< std::pair< uri,
boost::uint32_t > > 
hamcast::ipc::group_set (interface_id iid)
 
std::vector< uri > hamcast::ipc::neighbor_set (interface_id iid)
 
std::vector< uri > hamcast::ipc::children_set (interface_id iid, const uri &group)
 
std::vector< uri > hamcast::ipc::parent_set (interface_id iid, const uri &group)
 
bool hamcast::ipc::designated_host (interface_id iid, const uri &group)
 
void hamcast::ipc::enable_events ()
 
void hamcast::ipc::disable_events ()
 
boost::uint32_t hamcast::ipc::get_atomic_msg_size (interface_id iid)
 

Detailed Description

HAMcast sockets don't access any network interface. They serve as stub interface only. All member function calls are forwarded to the HAMcast middleware. This section describes the (binary) IPC protocol.

Connection establishment


ipc_init.png


Structure of an IPC message


header_general.png


Example protocol sequence diagrams

To send asynchronous multicast packages, you first need to create a socket and create a send stream on that socket with synchronous request messages.

This example shows a sequence, where a client sends seven multicast message to the group "ip://239.0.0.1". Note, that the client has to cache each send message, until he received an ACK message. The middleware discards messages, if the internal send buffer is full. In this case, the middleware sends a retransmit message with the first discarded sequence number.

The middleware expects serially numbered messages starting with 0 and "out-of-order" are ignored.


ipc_sequence.png


create_socket() is a synchronous request message with function_id = fid_create_socket and an empty content field (cs = 0). The middleware then sends a synchronous response message with a serialized socket_id in the content field:

// this example code shows, how to create a multicast socket via IPC
// it's NOT a recommendation to implement IPC this way, because this
// code neither checks for any errors nor is it "good" or safe
// (because the middleware might send an asynchronous event message
// instead of the expected synchronous response)
using namespace hamcast;
using namespace hamcast::ipc;
using namespace hamcast::util;
// a native (localhost) socket,
// connected to the middleware
socket_t s = ...;
int socket_flags = 0;
// send a create_socket() response
request_id rid = 0;
uint32_t cs = 0;
send(s, &mtype, sizeof(message_type), socket_flags);
send(s, &fid, sizeof(function_id), socket_flags);
send(s, &rid, sizeof(request_id), socket_flags);
send(s, &cs, sizeof(uint32_t), socket_flags);
// receive the synchronous response
message_type recv_mtype;
exception_id recv_eid;
request_id recv_rid;
uint32_t recv_cs;
char* recv_content;
recv(s, &recv_mtype, sizeof(message_type), socket_flags);
recv(s, &recv_eid, sizeof(exception_id), socket_flags);
recv(s, &recv_rid, sizeof(request_id), socket_flags);
recv(s, &recv_cs, sizeof(uint32_t), socket_flags);
recv_content = new char[recv_cs];
recv(s, recv_content, recv_cs, socket_flags);
// check received message
assert(recv_mtype == sync_response);
assert(recv_eid == eid_none);
assert(recv_rid == rid);
assert(recv_cs > 0);
// deserialize the socket id from the content field
deserializer d(new read_buffer(recv_cs, recv_content));
socket_id result;
d >> result;

Typedef Documentation

typedef boost::uint32_t hamcast::ipc::request_id

Describes the ID of a synchronous request.

typedef boost::uint32_t hamcast::ipc::sequence_number

Describes the ID of an asynchronous send data package.

typedef boost::uint16_t hamcast::ipc::stream_id

Describes the ID of an asynchronous data stream.

Enumeration Type Documentation

Holds the ID of an exception that was thrown during invocation of a synchronous request.

Enumerator
eid_none 

Indicates that no exception occured.

eid_requirement_failed 

Indicates that a requirement in the invoked function failed.

This causes a synchronous request to throw an instance of requirement_failed.

eid_internal_interface_error 

Indicates that an unexpected exception in a middleware module occured.

This causes a synchronous request to throw an instance of internal_interface_error.

Holds the function ID of an IPC request.

Enumerator
fid_create_socket 

Create a new multicast socket.

The result of this function is a socket_id.

fid_delete_socket 

Delete a multicast socket.

This function has no result.

fid_create_send_stream 

Create a new (outgoing) stream on a multicast socket.

The result of this function is a socket_id.

Describes the first header field of an IPC message and determines the interpretation of the other header fields.For the general structure of an IPC message see Structure of an IPC message.

Enumerator
sync_request 

A synchronous request message.


header_sync_request.png


This causes the middleware to invoke the requestet function and respond with an sync_response message with either the serialized result or an error message describing an occured exception during invocation.

sync_response 

A response to a synchronous request.


header_sync_response.png


Belongs to the request message with equal {request id} and contains either the serialized result value of the invoked function or an error string describing an exception that occured during invocation.

async_event 

Asynchronous transmission of an event.


header_async_event.png


Asynchronous transmission of a memebership event.

async_send 

Asynchronous transmission of an outgoing multicast packet.


header_async_send.png


Send multicast data to the middleware with outoing socket = {socket id}. The outgoing group is identified by {stream id}.

async_recv 

Asynchronous transmission of an incoming multicast packet.


header_async_recv.png


Transmission of a received multicast data packet for a joined group. The client deserializes a multicast_packet object from the content field.

cumulative_ack 

Indicates that the middleware has accepted outgoing multicast packets and will deliver them.

Note
Picture is outdated, no longer contains {stream_id}.


header_cumulative_ack.png


Forces the client to remove all outoing packages with a smaller or equal sequence nr from its buffer.

retransmit 

Indicates that the middleware has discarded multicast packets (e.g. because of a full buffer) and requests a retransmission.

Note
Picture is outdated, no longer contains {stream_id}.


header_retransmit.png


Forces the client to retransmit all packages in its buffer starting with the package that has the given {sequence nr}.

Function Documentation

void hamcast::ipc::add_sock_interface ( socket_id  sid,
interface_id  iid 
)

Force the socket to use the given interface.

Parameters
sidThe socket ID.
iidThe ID of the interface you want to add.
Warning
You should not call this functor manually. It is used by multicast_socket::add_interface.
std::vector<uri> hamcast::ipc::children_set ( interface_id  iid,
const uri &  group 
)

Get a set of child nodes that receive multicast data from a specified interface for a given group.

Parameters
iidThe (parent) interface ID.
groupThe multicast group.
Returns
A list of addresses, encoded as URIs.
stream_id hamcast::ipc::create_send_stream ( socket_id  sid,
const uri &  group 
)

Create a new output stream.

Parameters
sidThe outgoing socket.
groupThe outgoing multicast group.
Returns
A new multicast stream id, that's assigned to sid.
Warning
You should not call this functor manually. It is used by multicast_socket::send implicitly.
socket_id hamcast::ipc::create_socket ( )

Create a new socket and return the id of the newly created socket.

Returns
A new multicast socket id.
Warning
You should not call this functor manually. It is used by multicast_socket::multicast_socket.
void hamcast::ipc::del_sock_interface ( socket_id  sid,
interface_id  iid 
)

Remove the given interface from a socket.

Parameters
sidThe socket ID.
iidThe ID of the interface you want to remove.
Warning
You should not call this functor manually. It is used by multicast_socket::del_interface.
void hamcast::ipc::delete_socket ( socket_id  sid)

Delete a socket (this leaves all groups).

Parameters
sidThe ID of the socket that should be deleted.
Warning
You should not call this functor manually. It is used by multicast_socket::~multicast_socket.
bool hamcast::ipc::designated_host ( interface_id  iid,
const uri &  group 
)

Inquire whetever the host has the role of a designated forwarder resp. querier, or not.

Parameters
iidThe interface ID.
groupThe multicast group.
Returns
true if the host has the role of a designated forwarder for the multicast group group on the interface iid; otherwise false.
void hamcast::ipc::disable_events ( )

Disable membership events for this application.

void hamcast::ipc::enable_events ( )

Enable this application to receive membership events.

boost::uint32_t hamcast::ipc::get_atomic_msg_size ( interface_id  iid)

Get the current atomic message size of iid.

Parameters
iidThe interface ID.
Returns
Current atomic message size.
std::vector<interface_property> hamcast::ipc::get_interfaces ( )

Get all known multicast interfaces.

Returns
All known interfaces (meta informations and ID).
std::vector<interface_id> hamcast::ipc::get_sock_interfaces ( socket_id  sid)

Get all interfaces that are assigned to a given socket.

Parameters
sidThe ID of a socket.
Returns
A vector of all interfaces that are assigned to sid (might be empty).
Warning
You should not call this functor manually. It is used by multicast_socket::interfaces().
std::vector<std::pair<uri, boost::uint32_t> > hamcast::ipc::group_set ( interface_id  iid)

Returns all registered multicast groups on a given interface.

All groups are given as a pair of an uint32_t and an uri. The uint32_t is 0 if the uri is registered in listener state, 1 if the uri is registered in sender state and 2 if it's registered in both sender and listener state.

Parameters
iidThe interface ID.
Returns
All registered (and known) multicast groups on the interface iid.
void hamcast::ipc::join ( socket_id  sid,
const uri &  group 
)

Join a multicast group.

Parameters
sidThe ID of the socket.
groupThe multicast group you want to join.
Warning
You should not call this functor manually. It is used by multicast_socket::join.
void hamcast::ipc::leave ( socket_id  sid,
const uri &  group 
)

Leave a multicast group.

Parameters
sidThe ID of the socket.
groupThe multicast group you want to leave.
Warning
You should not call this functor manually. It is used by multicast_socket::leave.
std::vector<uri> hamcast::ipc::neighbor_set ( interface_id  iid)

Get all known multicast routing neighbors on a given interface.

Parameters
iidThe interface ID.
Returns
All registered multicast groups on the interface iid.
std::vector<uri> hamcast::ipc::parent_set ( interface_id  iid,
const uri &  group 
)

Get a set of neighbors from which the current node receives multicast data at a given interface for the specified group.

Parameters
iidThe interface ID.
groupThe multicast group.
Returns
A list of addresses, encoded as URIs.
void hamcast::ipc::set_sock_interfaces ( socket_id  sid,
const std::vector< interface_id > &  ifs 
)

Force the socket to use only the given interfaces.

Parameters
sidThe socket ID.
ifsA vector of (valid) interface IDs.
Precondition
!ifs.empty()
Warning
You should not call this functor manually. It is used by multicast_socket::set_interfaces.
void hamcast::ipc::set_ttl ( socket_id  sid,
boost::uint8_t  value 
)

Set the TTL value for a socket.

Parameters
sidThe ID of the socket.
valueThe new maximum hop count value.
Warning
You should not call this functor manually. It is used by multicast_socket::set_ttl.