0,0 → 1,249 |
//fsf_distributed.h |
//===================================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
// FF IIR RR SS |
// FF IR SS |
// FFFFFF RRRR SSSSST |
// FF FI RRR SS |
// FF II RRR SS |
// FF IIIIIR RS |
// |
// FSF(FIRST Scheduling Framework) |
// distributed services functionality |
//===================================================================== |
|
#include "fsf_core.h" |
|
#ifndef _FSF_DISTRIBUTED_H_ |
#define _FSF_DISTRIBUTED_H_ |
|
#define FSF_DISTRIBUTED_MODULE_SUPPORTED 1 |
|
|
//This operation identifies a contract as a |
//bandwidth reservation on the network identified |
//by the network input parameter. Then the |
//contract negotiation is performed using the |
//conventional negotiation functions, including |
//the possibility of grouping the contract with |
//others. If the network_id given is |
//FSF_NULL_NETWORK_ID, the contract is considered |
//not to reserve bandwidth in a network but to |
//operate as any other regular contract. It |
//returns 0 if successful, or FSF_ERR_BAD_ARGUMENT |
//if contract is null or the network id is not |
//valid. |
|
int |
fsf_set_contract_network_id |
(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 a regular |
//one and therefore has not a network_id set, it |
//puts the FSF_NULL_NETWORK_ID constant instead. |
//it returns 0 if successful, or |
//FSF_ERR_BAD_ARGUMENT if any of the pointers is |
//null. |
|
int |
fsf_get_contract_network_id |
(const fsf_contract_parameters_t *contract, |
fsf_network_id_t *network_id); |
|
//Transmission services: |
|
//opaque types for fsf endpoints |
typedef FSF_SEND_ENDPOINT_T_OPAQUE fsf_send_endpoint_t; |
typedef FSF_RECEIVE_ENDPOINT_T_OPAQUE fsf_receive_endpoint_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_node_address_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 |
typedef unsigned int fsf_port_t; |
|
//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. |
//It returns 0 if |
//successful. It returns FSF_ERR_BAD_ARGUMENT if |
//the endpoint is null, if the network_id is not |
//valid, or if the receiver or the port do not |
//conform to their expected formats. |
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 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. |
//It returns 0 if successful, |
//or FSF_ERR_BAD_ARGUMENT if the endpoint is not |
//valid. |
int |
fsf_destroy_send_endpoint |
(fsf_send_endpoint_t *endpoint); |
|
//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. It returns 0 if successful, or |
//FSF_ERR_BAD_ARGUMENT if the endpoint is not |
//valid. |
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 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. |
//The operation returns 0 if successful, or |
//FSF_ERR_BAD_ARGUMENT if the endpoint or the server |
//are not valid, it also fails with a |
//value of FSF_ERR_ALREADY_BOUND if the server is |
//already bound to some other send endpoint. |
//It fails with FSF_ERR_WRONG_NETWORK if the server |
//network id is not the same as the one in the endpoint |
int |
fsf_bind_endpoint_to_server |
(fsf_server_id_t 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. The operation fails with |
//FSF_ERR_NOT_BOUND if the endpoint has no server |
//bound |
int |
fsf_unbind_endpoint_from_server |
(fsf_send_endpoint_t *endpoint); |
|
//This operation copies the id of the server that |
//is bound to the specified send endpoint into the |
//variable pointed to by server. It returns 0 if |
//successful, or FSF_ERR_BAD_ARGUMENT if the |
//endpoint is not valid or server is NULL |
int |
fsf_get_endpoint_server |
(const fsf_send_endpoint_t *endpoint, |
fsf_server_id_t *server); |
|
//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 It returns 0 if successful, but it |
//fails with FSF_ERR_BAD_ARGUMENT if endpoint is not valid; it fails |
//with FSF_ERR_NOT_BOUND is not bound to a valid server; it fails with |
//FSF_ERR_TOO_LARGE if the message is too large for the network |
//protocol; it fails with FSF_ERR_BUFFER_FULL if the sending queue is |
//full |
int |
fsf_send |
(const fsf_send_endpoint_t *endpoint, |
void *msg, |
size_t size); |
|
//This operation creates a receive endpoint with all the information |
//that is necessary to receive information from the specified network |
//and port It returns 0 if successful, but it fails with |
//FSF_ERR_BAD_ARGUMENT if the port or the network id are not valid. |
int |
fsf_create_receive_endpoint |
(fsf_network_id_t network_id, |
fsf_port_t port, |
fsf_receive_endpoint_t *endpoint); |
|
//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. The function fails with |
//FSF_ERR_NO_SPACE if the buffersize is too small for the message |
//received (in which case the message is lost), or with |
//FSF_ERR_BAD_ARGUMENT if the endpoint is not valid, or if buffer or |
//messagesize are NULL. 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. |
int |
fsf_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 of |
//FSF_ERR_NO_MESSAGES |
int |
fsf_try_receive |
(const fsf_receive_endpoint_t *endpoint, |
void *buffer, |
size_t buffersize, |
size_t *messagesize); |
|
//This operation is used to calculate the minimum and/or maximum |
//budgets used in the preparation of network contracts. It puts in the |
//variable pointed to by budget the transmission time that it takes to |
//send a message of size msg_size through the network designated by |
//network_id, when there is no contention, but including any network |
//overheads It returns FSF_ERR_BAD_ARGUMENT if network_id is not a |
//valid identifier or if budget is a NULL pointer. |
int |
fsf_tx_time |
(fsf_network_id_t network_id, |
size_t msg_size, |
struct timespec *budget); |
|
//This operation is used to obtain the maximum message size for the |
//specified network It returns FSF_ERR_BAD_ARGUMENT if network_id is |
//not a valid identifier or if max_msg_size is NULL |
int |
fsf_max_message_size |
(fsf_network_id_t network_id, |
size_t *max_msg_size); |
|
|
#endif // _FSF_DISTRIBUTED_H_ |