| 1,3 → 1,7 |
|---|
| /** |
| @file Distributed. |
| */ |
| |
| //fsf_distributed.h |
| //===================================================================== |
| // FFFFFFIII RRRRR SSTTTTTTT |
| 20,36 → 24,36 |
|---|
| #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. |
| /** |
| |
| \ingroup distjmodule |
| |
| 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. |
| \ingroup distjmodule |
| |
| 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, |
| 61,34 → 65,40 |
|---|
| 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 |
| /** |
| \ingroup distjmodule |
| |
| 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 |
| /** |
| \ingroup distjmodule |
| |
| 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. |
| /** |
| |
| \ingroup distjmodule |
| |
| 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, |
| 96,25 → 106,28 |
|---|
| 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. |
| /** |
| \ingroup distjmodule |
| |
| 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. |
| /** |
| \ingroup distjmodule |
| |
| 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, |
| 122,59 → 135,67 |
|---|
| 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 |
| /** |
| \ingroup distjmodule |
| |
| 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); |
| 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 |
| /** |
| \ingroup distjmodule |
| |
| 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 |
| /** |
| \ingroup distjmodule |
| |
| 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 |
| |
| /** |
| \ingroup distjmodule |
| |
| 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, |
| 181,10 → 202,14 |
|---|
| 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. |
| /** |
| \ingroup distjmodule |
| |
| 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, |
| 191,20 → 216,23 |
|---|
| 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. |
| /** |
| \ingroup distjmodule |
| |
| 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, |
| 212,11 → 240,13 |
|---|
| 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 |
| /** |
| \ingroup distjmodule |
| |
| 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, |
| 224,13 → 254,17 |
|---|
| 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. |
| /** |
| \ingroup distjmodule |
| |
| 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, |
| 237,9 → 271,12 |
|---|
| 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 |
| /** |
| \ingroup distjmodule |
| |
| 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, |