Distributed module

Typedefs
typedef unsigned int	fsf_node_address_t
typedef unsigned int	fsf_port_t
Functions
int	fsf_set_contract_network_id (fsf_contract_parameters_t *contract, fsf_network_id_t network_id)
int	fsf_get_contract_network_id (const fsf_contract_parameters_t *contract, fsf_network_id_t *network_id)
int	fsf_create_send_endpoint (fsf_network_id_t network_id, fsf_node_address_t receiver, fsf_port_t port, fsf_send_endpoint_t *endpoint)
int	fsf_destroy_send_endpoint (fsf_send_endpoint_t *endpoint)
int	fsf_get_send_endpoint_parameters (const fsf_send_endpoint_t *endpoint, fsf_network_id_t *network_id, fsf_node_address_t *receiver, fsf_port_t *port)
int	fsf_bind_endpoint_to_server (fsf_server_id_t server, fsf_send_endpoint_t *endpoint)
int	fsf_unbind_endpoint_from_server (fsf_send_endpoint_t *endpoint)
int	fsf_get_endpoint_server (const fsf_send_endpoint_t *endpoint, fsf_server_id_t *server)
int	fsf_send (const fsf_send_endpoint_t *endpoint, void *msg, size_t size)
int	fsf_create_receive_endpoint (fsf_network_id_t network_id, fsf_port_t port, fsf_receive_endpoint_t *endpoint)
int	fsf_destroy_receive_endpoint (fsf_receive_endpoint_t *endpoint)
int	fsf_get_receive_endpoint_parameters (fsf_receive_endpoint_t *endpoint, fsf_network_id_t *network_id, fsf_port_t *port)
int	fsf_receive (const fsf_receive_endpoint_t *endpoint, void *buffer, size_t buffersize, size_t *messagesize)
int	fsf_try_receive (const fsf_receive_endpoint_t *endpoint, void *buffer, size_t buffersize, size_t *messagesize)
int	fsf_packet_tx_time (fsf_network_id_t network_id, struct timespec *budget)
int	fsf_packet_size (fsf_network_id_t network_id, size_t *packet_size)
int	fsf_max_message_size (fsf_network_id_t network_id, size_t *max_msg_size)

---

Detailed Description

:

---

Typedef Documentation

typedef unsigned int fsf_node_address_t

The node_address type specifies the node address in a communication-protocol-independent way. The actual address is obtained via a configuration dependent mapping function

typedef unsigned int fsf_port_t

The port type specifies the information that is necessary to get in contact with the thread in the receiving node, in a protocol-independent way. The actual port number is obtained via a configuration dependent mapping function

---

Function Documentation

int fsf_bind_endpoint_to_server (  fsf_server_id_t  server, fsf_send_endpoint_t *  endpoint )

This operation associates a send endpoint with a server, which means that messages sent through that endpoint will consume the server's reserved bandwidth and its packets will be sent according to the contract established for that server. If the endpoint is already bound to another server, it is effectively unbound from it and bound to the specified one. Parameters: [in]  server server id endpoint  pointer to the endpoint Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid or server is not valid. FSF_ERR_ALREADY_BOUND  if the server is already bound to some other send endpoint FSF_ERR_WRONG_NETWORK  if the server network id is not the same as the one in the endpoint

int fsf_create_receive_endpoint (  fsf_network_id_t  network_id, fsf_port_t  port, fsf_receive_endpoint_t *  endpoint )

This operation creates a receive endpoint with all the information that is necessary to receive information from the specified network and port Parameters: [in]  network_id the identifier ot the network to use [in]  port protocol dependent information used to identify the calling process as an expecting destination [out]  endpoint pointer to the variable that will contain the receive endpoint Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, network_id is not valid or if port do not conform to the expected format

int fsf_create_send_endpoint (  fsf_network_id_t  network_id, fsf_node_address_t  receiver, fsf_port_t  port, fsf_send_endpoint_t *  endpoint )

This operation creates a unidirectional input data endpoint through which, after the corresponding binding, it is possible to send data. network_id identifies the network to use, receiver specifies the communication protocol dependent information that is necessary to address the receiving node, and port specifies the communication protocol dependent information that is necessary to get in contact with the desired destination. Parameters: [in]  network_id the identifier ot the network to use [in]  receiver protocol dependent information used to address the receiving node [in]  port protocol dependent information used to get in contact with the desired destination process [out]  endpoint pointer to the variable that will contain the send endpoint Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, netwok_id is not valid or if the receiver or the port do not conform to their expected formats

int fsf_destroy_receive_endpoint (  fsf_receive_endpoint_t *  endpoint  )

This operation eliminates any resources reserved for the given endpoint. After callling this operation the endpoint can not be further used to invoke receive operations on it. Parameters: endpoint  pointer to the endpoint Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid

int fsf_destroy_send_endpoint (  fsf_send_endpoint_t *  endpoint  )

This operation eliminates any resources reserved for the referenced endpoint. If the endpoint is bound to a network server, it is unbound from it and can not be further used to invoke send operations on it. Parameters: endpoint  pointer to the endpoint to eliminate Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid

int fsf_get_contract_network_id (  const fsf_contract_parameters_t *  contract, fsf_network_id_t *  network_id )

This operation puts the network identification corresponding to the contract parameters object pointed to by contract in the variable pointed to by network_id. If the contract is not a network one and therefore has not a network_id set, it puts the FSF_NULL_NETWORK_ID constant instead. Parameters: [in]  contract the pointer to the contract object [out]  network_id pointer to the variable that will contain the network identifier Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if any of the pointers is null.

int fsf_get_endpoint_server (  const fsf_send_endpoint_t *  endpoint, fsf_server_id_t *  server )

This operation copies the id of the server that is bound to the specified send endpoint into the variable pointed to by server. Parameters: [in]  endpoint pointer to the endpoint [out]  server pointer to variable the will contain the server id Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid or server is NULL.

int fsf_get_receive_endpoint_parameters (  fsf_receive_endpoint_t *  endpoint, fsf_network_id_t *  network_id, fsf_port_t *  port )

This operation returns in the variables network_id, and port, the corresponding parameters used in the creation of the given receive endpoint. Parameters: [in]  endpoint pointer to the endpoint [out]  network_id pointer to variable the will contain the network id [out]  port pointer to variable the will contain the protocol dependent information used to get in contact with the desired destination process Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid or all the other pointers are NULL.

int fsf_get_send_endpoint_parameters (  const fsf_send_endpoint_t *  endpoint, fsf_network_id_t *  network_id, fsf_node_address_t *  receiver, fsf_port_t *  port )

This operation returns (except for those NULL arguments) in the variables pointed to by network_id, receiver, or port, the corresponding parameters used in the creation of the given send endpoint. Parameters: [in]  endpoint pointer to the endpoint [out]  network_id pointer to variable the will contain the network id [out]  receiver pointer to variable the will contain the protocol dependent information used to address the receiving node [out]  port pointer to variable the will contain the protocol dependent information used to get in contact with the desired destination process Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid or all the other pointers are NULL.

int fsf_max_message_size (  fsf_network_id_t  network_id, size_t *  max_msg_size )

This operation is used to obtain the maximum number of packets of which a message can be formed, for the specified network. A message is defined as the piece of information used in a send operation. Since the value returned by this operation is measured in packet units, the effective size can be calculated multiplying this value by the size of a packet. When the value returned by this operation is larger than 1 it means the implementation will make the partition of messages into packets and its recomposition at the receiving node. Parameters: [in]  network_id the identifier ot the network to use [out]  max_msg_size pointer to the variable tha will contain the maximum number of packets sent in a single send operation Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if network_id is not a valid network identifier of if max_msg_size is a NULL pointer

int fsf_packet_size (  fsf_network_id_t  network_id, size_t *  packet_size )

This operation puts in the variable pointed to by packet_size the maximum number of bytes that can be sent in a packet through the network designated by network_id. It is usually a configuration value and it helps the user application to calculate the number of packets it will need to reserve for the periodic transmision of its messages and prepare the corresponding contracts. Parameters: [in]  network_id the identifier ot the network to use [out]  packet_size pointer to the variable tha will contain the maximum size in bytes of a packet Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if network_id is not a valid network identifier of if packet_size is a NULL pointer

int fsf_packet_tx_time (  fsf_network_id_t  network_id, struct timespec *  budget )

This operation is used to calculate a budget represented as a time magnitude, for a specified network. If succesful, the operation puts in the variable pointed to by budget the transmission time that it takes to send a packet through the network designated by network_id, when there is no contention, but including any network overheads. Parameters: [in]  network_id the identifier ot the network to use [out]  budget pointer to the variable tha will contain the time it takes to transmitt a packet Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if network_id is not a valid network identifier of if budget is a NULL pointer

int fsf_receive (  const fsf_receive_endpoint_t *  endpoint, void *  buffer, size_t  buffersize, size_t *  messagesize )

If there are no messages available in the specified receive endpoint this operation blocks the calling thread waiting for a message to be received. When a message is available, if its size is less than or equal to the buffersize, the function stores it in the variable pointed to by buffer and puts the number of bytes received in the variable pointed to by messagesize. Messages arriving at a receiver buffer that is full will be silently discarded. The application is responsible of reading the receive endpoints with appropriate regularity, or of using a sequence number or some other mechanism to detect any lost messages. Parameters: endpoint  pointer to the endpoint [out]  buffer pointer to the place that will contain the message received [in]  buffersize size of the buffer space [out]  messagesize pointer to the variable that will contain the number of bytes received Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid or if buffer or messagesize are NULL. FSF_ERR_NO_SPACE  if the buffersize is too small for the message received (in which case the message is lost).

int fsf_send (  const fsf_send_endpoint_t *  endpoint, void *  msg, size_t  size )

This operation sends a message stored in msg and of length size through the given endpoint. The operation is non-blocking and returns immediately. An internal fsf service will schedule the sending of messages and implement the communications sporadic server corresponding to the network server bound to the given endpoint. Messages sent through the same endpoint are received in the same order in which they were sent Parameters: endpoint  pointer to the endpoint [in]  msg pointer to the message [in]  size number of bytes to transmitt Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid or msg is NULL FSF_ERR_NOT_BOUND  if endpoint is not bound to a valid server; FSF_ERR_TOO_LARGE  if the message is too large for the network protocol FSF_ERR_BUFFER_FULL  if the sending queue is full

int fsf_set_contract_network_id (  fsf_contract_parameters_t *  contract, fsf_network_id_t  network_id )

This operation sets the network id attribute in the contract pointed to by contract, to the value specified by network_id. When a contract is negotiated, if network_id is FSF_NULL_NETWORK_ID (which is the default value) the contract is negotiated for the processing capacity of the node making the call. If network_id represents a valid network identifier, the negotiation is carried out for the specified network. Parameters: contract  the pointer to the contract object [in]  network_id the network identifier Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if contract is null or the network id is not valid.

int fsf_try_receive (  const fsf_receive_endpoint_t *  endpoint, void *  buffer, size_t  buffersize, size_t *  messagesize )

This operation is the same as fsf_receive, except that if there are no messages available in the specified receive endpoint at the time of the call the operation returns with an error Parameters: endpoint  pointer to the endpoint [out]  buffer pointer to the place that will contain the message received [in]  buffersize size of the buffer space [out]  messagesize pointer to the variable that will contain the number of bytes received Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid or if buffer or messagesize are NULL. FSF_ERR_NO_SPACE  if the buffersize is too small for the message received (in which case the message is lost). FSF_ERR_NO_MESSAGES  if there are no messages available in the specified receive endpoint at the time of the call

int fsf_unbind_endpoint_from_server (  fsf_send_endpoint_t *  endpoint  )

This operation unbinds a send endpoint from a server. Endpoints with no server associated cannot be used to send data, and they stay in that state until they are either eliminated or bound again. Parameters: endpoint  pointer to the endpoint to unbind Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if endpoint is null, or not valid FSF_ERR_NOT_BOUND  if the endpoint has no server bound

---