#ifndef _FRSH_DISTRIBUTED_H_
#define _FRSH_DISTRIBUTED_H_
+
+/**
+ * @file frsh_distributed.h
+ **/
+
+
#include "frsh_distributed_types.h"
#include "frsh_core_types.h"
* and the network contract will be canceled.
**/
+
#define FRSH_DISTRIBUTED_MODULE_SUPPORTED 1
//////////////////////////////////////////////////////////////////////
**/
/**
- * frsh_message_get_max_size()
+ * frsh_network_get_max_message_size()
+ *
+ * This operation gives the maximum number of bytes that can be sent
+ * at a time through the send function when using the network designated by
+ * 'resource_id' and sending it to 'destination'.
+ *
+ * If the application needs to send bigger messages it will have to
+ * split them.
+ *
+ * Some protocols, like IP, are capable of sending large messages
+ * (and use fragmentation internally) but other protocols don't.
*
- * This function gives the maximum size that a network supports for a
- * message.
+ * @param[in] resource_id The network we want the tx time from.
+ * @param[in] destination The destination address
+ * @param[out] max_size The maximum number of bytes for each message
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
+ * invalid \n
*
**/
-int frsh_message_get_max_size(frsh_resource_id_t network_id,
- size_t *max_msg_size);
+int frsh_network_get_max_message_size
+ (const frsh_resource_id_t resource_id,
+ const frsh_network_address_t destination,
+ size_t *max_size);
+/**
+ * frsh_network_bytes_to_budget()
+ *
+ * This operation converts a number of bytes into a temporal budget for
+ * a specific network. Network overheads are not included here but are
+ * considered internally when negotiating a specific contract.
+ *
+ * @param[in] resource_id The network
+ * @param[in] nbytes Number of bytes
+ * @param[out] budget The network budget for nbytes
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
+ * than zero \n
+ *
+ **/
+int frsh_network_bytes_to_budget
+ (const frsh_resource_id_t resource_id,
+ const size_t nbytes,
+ struct timespec *budget);
/**
- * frsh_message_get_tx_time()
+ * frsh_network_budget_to_bytes()
*
- * This function gives the maximum transmission time that a network
- * will need for a specified message. This includes any possible
- * overhead such as contention periods, headers, fragmentation, retries.
+ * This operation converts a temporal budget into a number of bytes for
+ * a specific network. Network overheads are not included.
*
- * @param[in] network_id Network through which the message will flow.
- * @param[in] message_size Number of bytes of the message
- * @param[out] max_tx_time Time needed to send the message.
+ * @param[in] resource_id The network
+ * @param[in] budget The network budget for nbytes
+ * @param[out] nbytes Number of bytes
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
+ * an invalid time value \n
*
**/
-int frsh_message_get_tx_time(frsh_resource_id_t network_id,
- size_t message_size,
- struct timespec *max_tx_time);
+int frsh_network_budget_to_bytes
+ (const frsh_resource_id_t resource_id,
+ const struct timespec *budget,
+ size_t *nbytes);
+
+/**
+ * frsh_network_get_min_effective_budget()
+ *
+ * This operation gets the minimum effective budget for a network. Each message
+ * consumes a contracted budget in "chunks" (i.e: packets) that we call
+ * minimum effective budget.
+ *
+ * A negotiated contract, for N bytes in a period T, means that there is a
+ * virtual resource that reserves for the user:
+ *
+ * Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
+ *
+ * Note that if the user decides not to send these N bytes at once but, say,
+ * one byte at a time, it will consume one "CHUNK" at a time and the reserved
+ * budget will become exhausted before sending all the bytes.
+ *
+ * @param[in] resource_id The network
+ * @param[out] budget The network budget
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int frsh_network_get_min_effective_budget
+ (const frsh_resource_id_t resource_id,
+ struct timespec *budget);
/**
* frsh_contract_set_queueing_info()
int frsh_contract_get_protocol_info(frsh_contract_t contract,
frsh_protocol_info_t *protocol_info);
-
/*@}*/
-
-
//////////////////////////////////////////////////////////////////////
// TRANSMISSION SERVICES
//////////////////////////////////////////////////////////////////////
(frsh_resource_id_t network_id,
frsh_network_address_t destination,
frsh_stream_id_t stream_id,
+ frsh_send_endpoint_protocol_info_t protocol_info,
frsh_send_endpoint_t *endpoint);
/**
(const frsh_send_endpoint_t *endpoint,
frsh_resource_id_t *network_id,
frsh_network_address_t *destination,
- frsh_stream_id_t *stream);
+ frsh_stream_id_t *stream,
+ frsh_send_endpoint_protocol_info_t *protocol_info);
/**
* frsh_send_endpoint_destroy()
* endpoint creation must correspond to the resource_id of the vres
* contract.
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT if the endpoint or the vres are not
- * valid
+ * valid \n
* FRSH_ERR_ALREADY_BOUND if the vres is already bound to some
- * other send endpoint.
+ * other send endpoint \n
* FRSH_ERR_WRONG_NETWORK if the vres network id is not the same
- * as the one in the endpoint
+ * as the one in the endpoint \n
**/
int frsh_send_endpoint_bind
(frsh_vres_id_t vres,
* no vres associated cannot be used to send data, and they stay in
* that state until they are either eliminated or bound again.
*
- * @return 0 if successful
- * FRSH_ERR_NOT_BOUND if the endpoint was not bound.
+ * @return 0 if successful \n
+ * FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
**/
int frsh_send_endpoint_unbind
(frsh_send_endpoint_t *endpoint);
* This operation copies the id of the vres that is bound to the
* specified send endpoint into the variable pointed to by vres.
*
- * @return 0 if successful
- * FRSH_ERR_NOT_BOUND if the endpoint was not bound.
+ * @return 0 if successful \n
+ * FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
* FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid or vres
- * is NULL
+ * is NULL \n
**/
int frsh_send_endpoint_get_vres_id
(const frsh_send_endpoint_t *endpoint,
* implement the communications sporadic vres corresponding to the
* network vres bound to the given endpoint.
*
- * @returns 0 if successful
- * FRSH_ERR_BAD_ARGUMENT if endpoint is not valid
- * FRSH_ERR_NOT_BOUND if endpoint is not bound to a valid vres
+ * @returns 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if endpoint is not valid \n
+ * FRSH_ERR_NOT_BOUND if endpoint is not bound to a valid vres \n
* FRSH_ERR_TOO_LARGE if the message is too large for the
- * network protocol
+ * network protocol \n
* FRSH_ERR_BUFFER_FULL if the message has been discarded
* because the queue is full (and does not
- * have the policy FRSH_QP_OLDEST.
+ * have the policy FRSH_QP_OLDEST \n
**/
int frsh_send_async
(const frsh_send_endpoint_t *endpoint,
void *msg,
size_t size);
-
-
/**
* frsh_send_endpoint_get_status()
*
* application.
* @param[in] endpoin Placeholder for the endpoint object.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT if the stream or the network id are not valid.
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if the stream or the network id are not
+ * valid \n
**/
int frsh_receive_endpoint_create
(frsh_resource_id_t network_id,
frsh_stream_id_t stream_id,
frsh_endpoint_queueing_info_t queueing_info,
- frsh_protocol_info_t protocol_info,
+ frsh_receive_endpoint_protocol_info_t protocol_info,
frsh_receive_endpoint_t *endpoint);
-
/**
* frsh_receive_endpoint_get_params()
*
* endpoint at creation time.
**/
int frsh_receive_endpoint_get_params
- (frsh_resource_id_t *network_id,
+ (const frsh_receive_endpoint_t *endpoint,
+ frsh_resource_id_t *network_id,
frsh_stream_id_t *stream,
frsh_endpoint_queueing_info_t *queueing_info,
- frsh_protocol_info_t *protocol_info,
- const frsh_receive_endpoint_t *endpoint);
+ frsh_receive_endpoint_protocol_info_t *protocol_info);
/**
* frsh_receive_endpoint_destroy()
* endpoints with appropriate regularity, or of using a sequence
* number or some other mechanism to detect any lost messages.
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
* buffer or message_size are NULL.\n
* FRSH_ERR_NO_SPACE if the message size is bigger than the
- * provided buffer.
+ * provided buffer \n
**/
int frsh_receive_sync
(const frsh_receive_endpoint_t *endpoint,
void *buffer,
size_t buffer_size,
- size_t *message_size);
+ size_t *message_size,
+ frsh_network_address_t *from);
/**
* frsh_receive_async()
* blocking (asynchronous) fashion. If no message is available it
* returns with error FRSH_NO_MESSAGE.
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
- * buffer or message_size are NULL.
- * FRSH_NO_MESSAGE if no messages are available in the queue.
+ * buffer or message_size are NULL \n
+ * FRSH_NO_MESSAGE if no messages are available in the queue \n
* FRSH_ERR_NO_SPACE if the message size is bigger than the
- * provided buffer.
+ * provided buffer \n
**/
int frsh_receive_async
(const frsh_receive_endpoint_t *endpoint,
void *buffer,
size_t buffer_size,
- size_t *message_size);
+ size_t *message_size,
+ frsh_network_address_t *from);
/**
projects / frescor / frsh-include.git / blobdiff