Classes | Typedefs | Enumerations

Inter-process communication.

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

Classes

class  hamcast::ipc::client_channel
 An IPC channel describing the connection from a client to the middleware. More...
class  hamcast::ipc::message
 Describes a single IPC message. More...
class  hamcast::ipc::middleware_configuration
 Stores the configuration of the currently running middleware. More...

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
}



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

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

Structure of an IPC message

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.

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
message_type mtype = sync_request;
function_id fid = fid_create_socket;
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.


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.


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.


Asynchronous transmission of a memebership event.

async_send 

Asynchronous transmission of an outgoing multicast packet.


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.


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.


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.


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:
sid The socket ID.
iid The 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:
iid The (parent) interface ID.
group The 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:
sid The outgoing socket.
group The 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:
sid The socket ID.
iid The 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:
sid The 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:
iid The interface ID.
group The 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.

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:
sid The 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:
iid The 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:
sid The ID of the socket.
group The 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:
sid The ID of the socket.
group The 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:
iid The 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:
iid The interface ID.
group The 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:
sid The socket ID.
ifs A 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:
sid The ID of the socket.
value The new maximum hop count value.
Warning:
You should not call this functor manually. It is used by multicast_socket::set_ttl.
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator