| 28,15 → 28,20 |
|---|
| |
| \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. |
| 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. |
| |
| @param contract the pointer to the contract object |
| @param [in] network_id the network identifier |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if contract is null or the network |
| id is not valid. |
| */ |
| int |
| fsf_set_contract_network_id |
| 46,13 → 51,20 |
|---|
| /** |
| |
| \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 not a network |
| one and therefore has not a network_id set, it |
| puts the FSF_NULL_NETWORK_ID constant instead. |
| |
| 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. |
| @param [in] contract the pointer to the contract object |
| @param [out] network_id pointer to the variable that will contain |
| the network identifier |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if any of the pointers is null. |
| */ |
| int |
| fsf_get_contract_network_id |
| 59,45 → 71,36 |
|---|
| (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; |
| |
| /** |
| \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; |
| |
| /** |
| \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. |
| |
| /** |
| |
| \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. |
| @param [in] network_id the identifier ot the network to use |
| @param [in] receiver protocol dependent information used |
| to address the receiving node |
| @param [in] port protocol dependent information used |
| to get in contact with the desired destination process |
| @param [out] endpoint pointer to the variable that will |
| contain the send endpoint |
| |
| @retval 0 if the operation is succesful |
| @retval 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_create_send_endpoint |
| 109,11 → 112,16 |
|---|
| /** |
| \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. |
| 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. |
| |
| @param endpoint pointer to the endpoint to eliminate |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| */ |
| int |
| fsf_destroy_send_endpoint |
| 122,11 → 130,26 |
|---|
| /** |
| \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. |
| 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. |
| |
| @param [in] endpoint pointer to the endpoint |
| @param [out] network_id pointer to variable the will contain |
| the network id |
| @param [out] receiver pointer to variable the will contain |
| the protocol dependent information used to address the |
| receiving node |
| @param [out] port pointer to variable the will contain |
| the protocol dependent information used to get in contact |
| with the desired destination process |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| or all the other pointers are NULL. |
| |
| */ |
| int |
| fsf_get_send_endpoint_parameters |
| 138,17 → 161,26 |
|---|
| /** |
| \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 */ |
| 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. |
| |
| @param [in] server server id |
| @param endpoint pointer to the endpoint |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| or server is not valid. |
| @retval FSF_ERR_ALREADY_BOUND if the server is already |
| bound to some other send endpoint |
| @retval 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, |
| 157,11 → 189,19 |
|---|
| /** |
| \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 */ |
| 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. |
| |
| @param endpoint pointer to the endpoint to unbind |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| @retval FSF_ERR_NOT_BOUND if the endpoint has no server |
| bound |
| */ |
| int |
| fsf_unbind_endpoint_from_server |
| (fsf_send_endpoint_t *endpoint); |
| 169,11 → 209,17 |
|---|
| /** |
| \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 |
| This operation copies the id of the server that |
| is bound to the specified send endpoint into the |
| variable pointed to by server. |
| |
| @param [in] endpoint pointer to the endpoint |
| @param [out] server pointer to variable the will contain |
| the server id |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| or server is NULL. |
| */ |
| int |
| fsf_get_endpoint_server |
| 184,18 → 230,27 |
|---|
| /** |
| \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 */ |
| 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 |
| |
| @param endpoint pointer to the endpoint |
| @param [in] msg pointer to the message |
| @param [in] size number of bytes to transmitt |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| or msg is NULL |
| @retval FSF_ERR_NOT_BOUND if endpoint is not bound to a valid |
| server; |
| @retval FSF_ERR_TOO_LARGE if the message is too large for the |
| network protocol |
| @retval FSF_ERR_BUFFER_FULL if the sending queue is full |
| */ |
| int |
| fsf_send |
| (const fsf_send_endpoint_t *endpoint, |
| 205,11 → 260,20 |
|---|
| /** |
| \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. */ |
| This operation creates a receive endpoint with all the information |
| that is necessary to receive information from the specified network |
| and port |
| |
| @param [in] network_id the identifier ot the network to use |
| @param [in] port protocol dependent information used |
| to identify the calling process as an expecting destination |
| @param [out] endpoint pointer to the variable that will |
| contain the receive endpoint |
| |
| @retval 0 if the operation is succesful |
| @retval 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_receive_endpoint |
| (fsf_network_id_t network_id, |
| 219,20 → 283,30 |
|---|
| /** |
| \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.*/ |
| 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. |
| |
| @param endpoint pointer to the endpoint |
| @param [out] buffer pointer to the place that will contain |
| the message received |
| @param [in] buffersize size of the buffer space |
| @param [out] messagesize pointer to the variable that will contain |
| the number of bytes received |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| or if buffer or messagesize are NULL. |
| @retval FSF_ERR_NO_SPACE if the buffersize is too small for the |
| message received (in which case the message is lost). |
| */ |
| int |
| fsf_receive |
| (const fsf_receive_endpoint_t *endpoint, |
| 243,10 → 317,26 |
|---|
| /** |
| \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 */ |
| 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 |
| |
| @param endpoint pointer to the endpoint |
| @param [out] buffer pointer to the place that will contain |
| the message received |
| @param [in] buffersize size of the buffer space |
| @param [out] messagesize pointer to the variable that will contain |
| the number of bytes received |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if endpoint is null, or not valid |
| or if buffer or messagesize are NULL. |
| @retval FSF_ERR_NO_SPACE if the buffersize is too small for the |
| message received (in which case the message is lost). |
| @retval FSF_ERR_NO_MESSAGES if there are no messages available |
| in the specified receive endpoint at the time of the call |
| */ |
| int |
| fsf_try_receive |
| (const fsf_receive_endpoint_t *endpoint, |
| 257,26 → 347,73 |
|---|
| /** |
| \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, |
| size_t msg_size, |
| 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. |
| |
| @param [in] network_id the identifier ot the network to use |
| @param [out] budget pointer to the variable tha will contain |
| the time it takes to transmitt a packet |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if network_id is not a valid |
| network identifier of if budget is a NULL pointer |
| */ |
| int |
| fsf_packet_tx_time |
| (fsf_network_id_t network_id, |
| struct timespec *budget); |
| |
| /** |
| \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 */ |
| 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. |
| |
| @param [in] network_id the identifier ot the network to use |
| @param [out] packet_size pointer to the variable tha will contain |
| the maximum size in bytes of a packet |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if network_id is not a valid |
| network identifier of if packet_size is a NULL pointer |
| */ |
| int |
| fsf_packet_size |
| (fsf_network_id_t network_id, |
| size_t *packet_size); |
| |
| |
| /** |
| \ingroup distjmodule |
| |
| 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. |
| |
| @param [in] network_id the identifier ot the network to use |
| @param [out] max_msg_size pointer to the variable tha will contain |
| the maximum number of packets sent in a single send operation |
| |
| @retval 0 if the operation is succesful |
| @retval FSF_ERR_BAD_ARGUMENT if network_id is not a valid |
| network identifier of if max_msg_size is a NULL pointer |
| */ |
| int |
| fsf_max_message_size |
| (fsf_network_id_t network_id, |
| 283,4 → 420,5 |
|---|
| size_t *max_msg_size); |
| |
| |
| |
| #endif // _FSF_DISTRIBUTED_H_ |