typedef void *fna_vres_id_t;
/**
- * fna_vres_create()
+ * fna_contract_negotiate()
*
* The operation negotiates a contract and if accepted it will return
* a fna_vres_id_t. It will also check that the given contract_id is unique
* within the network.
*
- * In object oriented terminology it is similar to a constructor of the
- * virtual resource class.
- *
* If the on-line admission test is enabled, it determines whether the
* contract can be admitted or not based on the current contracts
* established in the network. Then it creates the vres and
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_vres_create
- (const frsh_resource_id_t resource_id,
- const frsh_contract_t *contract,
- fna_vres_id_t *vres);
+int fna_contract_negotiate
+ (const frsh_resource_id_t resource_id,
+ const frsh_contract_t *contract,
+ fna_vres_id_t *vres);
/**
- * fna_vres_renegotiate_sync()
+ * fna_contract_renegotiate_sync()
*
* The operation renegotiates a contract for an existing vres. If
* the on-line admission test is enabled it determines whether the
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_vres_renegotiate_sync
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- const frsh_contract_t *new_contract);
+int fna_contract_renegotiate_sync
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ const frsh_contract_t *new_contract);
/**
- * fna_vres_renegotiate_async()
+ * fna_contract_renegotiate_async()
*
* The operation enqueues a renegotiate operation for an existing
* vres, and returns immediately. The renegotiate operation is
* NULL nor a valid POSIX signal \n
*
**/
-int fna_vres_renegotiate_async
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- const frsh_contract_t *new_contract,
- frsh_signal_t signal_to_notify,
- frsh_signal_info_t signal_info);
+int fna_contract_renegotiate_async
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ const frsh_contract_t *new_contract,
+ frsh_signal_t signal_to_notify,
+ frsh_signal_info_t signal_info);
/**
* fna_vres_get_renegotiation_status()
*
**/
int fna_vres_get_renegotiation_status
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- frsh_renegotiation_status_t *renegotiation_status);
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ frsh_renegotiation_status_t *renegotiation_status);
/**
* fna_vres_destroy()
*
**/
int fna_vres_destroy
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres);
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres);
/**
* fna_vres_get_contract()
*
**/
int fna_vres_get_contract
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- frsh_contract_t *contract);
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ frsh_contract_t *contract);
/**
* fna_vres_get_usage()
*
**/
int fna_vres_get_usage
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- struct timespec *usage);
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *usage);
/**
* fna_vres_get_remaining_budget()
*
**/
int fna_vres_get_remaining_budget
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- struct timespec *remaining_budget);
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *remaining_budget);
/**
* fna_vres_get_budget_and_period()
*
**/
int fna_vres_get_budget_and_period
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- struct timespec *budget,
- struct timespec *period);
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *budget,
+ struct timespec *period);
/*@}*/
*
**/
int fna_resource_get_capacity
- (const frsh_resource_id_t resource_id,
- const int importance,
- uint32_t *capacity);
+ (const frsh_resource_id_t resource_id,
+ const int importance,
+ uint32_t *capacity);
/**
* fna_resource_get_total_weight()
*
**/
int fna_resource_get_total_weight
- (const frsh_resource_id_t resource_id,
- const int importance,
- int *total_weight);
+ (const frsh_resource_id_t resource_id,
+ const int importance,
+ int *total_weight);
/**
* fna_vres_decrease_capacity()
*
**/
int fna_vres_decrease_capacity
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- const struct timespec new_budget,
- const struct timespec new_period);
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ const struct timespec new_budget,
+ const struct timespec new_period);
/*@}*/
*
**/
int fna_send_sync
- (const frsh_send_endpoint_t *endpoint,
- const void *msg,
- const size_t size);
+ (const frsh_send_endpoint_t *endpoint,
+ const void *msg,
+ const size_t size);
/**
* fna_send_async()
*
**/
int fna_send_async
- (const frsh_send_endpoint_t *endpoint,
- const void *msg,
- const size_t size);
+ (const frsh_send_endpoint_t *endpoint,
+ const void *msg,
+ const size_t size);
/**
* fna_receive_sync()
*
**/
int fna_receive_sync
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
- const size_t buffer_size,
- size_t *received_bytes);
+ (const frsh_receive_endpoint_t *endpoint,
+ void *buffer,
+ const size_t buffer_size,
+ size_t *received_bytes);
/**
* fna_receive_async()
*
**/
int fna_receive_async
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
- const size_t buffer_size,
- size_t *received_bytes);
+ (const frsh_receive_endpoint_t *endpoint,
+ void *buffer,
+ const size_t buffer_size,
+ size_t *received_bytes);
/**
* fna_send_endpoint_get_status()
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_send_endpoint_get_status(const frsh_send_endpoint_t *endpoint,
- int *number_of_pending_messages,
- frsh_endpoint_network_status *network_status,
- frsh_protocol_status_t *protocol_status);
+int fna_send_endpoint_get_status
+ (const frsh_send_endpoint_t *endpoint,
+ int *number_of_pending_messages,
+ frsh_endpoint_network_status *network_status,
+ frsh_protocol_status_t *protocol_status);
/**
* fna_receive_endpoint_create()
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
**/
int fna_receive_endpoint_create
- (const frsh_resource_id_t resource_id,
- const frsh_stream_id_t stream_id,
- const frsh_endpoint_queueing_info_t queueing_info,
- const frsh_protocol_info_t protocol_info,
- frsh_receive_endpoint_t *endpoint);
+ (const frsh_resource_id_t resource_id,
+ const frsh_stream_id_t stream_id,
+ const frsh_endpoint_queueing_info_t queueing_info,
+ const frsh_protocol_info_t protocol_info,
+ frsh_receive_endpoint_t *endpoint);
/**
* fna_receive_endpoint_get_pending_messages
*
**/
int fna_receive_endpoint_get_status
- (const frsh_receive_endpoint_t *endpoint,
- int *number_of_pending_messages,
- frsh_endpoint_network_status *network_status,
- frsh_protocol_status_t *protocol_status);
+ (const frsh_receive_endpoint_t *endpoint,
+ int *number_of_pending_messages,
+ frsh_endpoint_network_status *network_status,
+ frsh_protocol_status_t *protocol_status);
/*@}*/
**/
/**
- * fna_message_get_tx_time()
+ * fna_network_message_get_max_size()
*
- * This operation gives the physical transmission time that it takes to
- * send a message of the nbytes size through the network designated by
- * resource_id, not including any network overheads (fragmentation in packets,
- * headers, retransmissions,...).
+ * 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'.
*
- * It is be used by the application to calculate the minimum and
- * maximum budgets used in the preparation of network contracts.
- * (Note that in the negotiation overheads must be taken into account)
+ * 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 doesn't
+ * provide fragmentation features.
*
* @param[in] resource_id The network we want the tx time from.
- * @param[in] nbytes Number of bytes of the message
- * @param[out] tx_time The transmission time for nbytes (without overheads)
+ * @param[in] destination The destination address
+ * @param[out] max_size The maximum number of bytes for each message
*
* @return
* FNA_NO_ERROR: in this case it also means contract accepted \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
- * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is bigger than
- * the maximum message size \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_message_get_tx_time
- (const frsh_resource_id_t resource_id,
- const size_t nbytes,
- struct timespec *tx_time);
+int fna_network_message_get_max_size
+ (const frsh_resource_id_t resource_id,
+ const frsh_network_address_t destination,
+ size_t *max_size);
/**
- * fna_message_get_max_size()
+ * fna_network_bytes_to_budget()
*
- * This operation gives the maximum number of bytes that can be sent
- * in a single message through the network designated by resource_id.
- * If the application needs to send bigger messages it will have to
- * split them. Some protocols like TCP/IP are capable of sending large
- * messages (and use fragmentation internally) but other protocols doesn't
- * provide fragmentation features so the maximum size will be the MTU itself.
+ * This operation converts a number of bytes into a temporal budget for
+ * a specific network. Network overheads are not included here but internally
+ * when negotiating a specific contract.
*
- * It is be used by the application to calculate the minimum and
- * maximum budgets used in the preparation of network contracts.
+ * @param[in] resource_id The network
+ * @param[in] nbytes Number of bytes
+ * @param[out] budget The network budget for nbytes
*
- * @param[in] resource_id The network we want the tx time from.
- * @param[out] max_size The maximum number of bytes for each message
+ * @return
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_network_bytes_to_budget
+ (const frsh_resource_id_t resource_id,
+ const size_t nbytes,
+ struct timespec *budget);
+
+/**
+ * fna_network_budget_to_bytes()
+ *
+ * This operation converts a temporal budget into a number of bytes for
+ * a specific network. Network overheads are not included.
+ *
+ * @param[in] resource_id The network
+ * @param[in] budget The network budget for nbytes
+ * @param[out] nbytes Number of bytes
*
* @return
* FNA_NO_ERROR: in this case it also means contract accepted \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
- * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is bigger than
- * the maximum message size \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+int fna_network_budget_to_bytes
+ (const frsh_resource_id_t resource_id,
+ const struct timespec *budget,
+ size_t *nbytes);
+
+/**
+ * fna_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
+ * effective budget.
+ *
+ * A negotiated contract, for N bytes in a period T, means that there is a
+ * virtual resource that reserves for the user:
+ *
+ * (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 more "CHUNKS" 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
+ * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_message_get_max_size
- (const frsh_resource_id_t resource_id,
- size_t *max_size);
+int fna_network_get_min_effective_budget
+ (const frsh_resource_id_t resource_id,
+ struct timespec *budget);
/*@}*/
projects / frescor / fna.git / commitdiff