-// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//----------------------------------------------------------------------
+// Copyright (C) 2006 - 2007 by the FRESCOR consortium:
//
// Universidad de Cantabria, SPAIN
// University of York, UK
// Scuola Superiore Sant'Anna, ITALY
// Kaiserslautern University, GERMANY
-// Univ. Politécnica Valencia, SPAIN
+// Univ. Politecnica Valencia, SPAIN
// Czech Technical University in Prague, CZECH REPUBLIC
// ENEA SWEDEN
// Thales Communication S.A. FRANCE
// Rapita Systems Ltd UK
// Evidence ITALY
//
-// See http://www.frescor.org for a link to partners' websites
+// See http://www.frescor.org
//
-// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// The FRESCOR project (FP6/2005/IST/5-034026) is funded
// in part by the European Union Sixth Framework Programme
// The European Union is not liable of any use that may be
// made of this code.
// Universidad de Cantabria, SPAIN
// University of York, UK
//
-// FSF API web pages: http://marte.unican.es/fsf/docs
-// http://shark.sssup.it/contrib/first/docs/
-//
-// This file is part of FRSH API
-//
-// FRSH API is free software; you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation; either version 2, or (at your option)
-// any later version.
-//
-// FRSH API is distributed in the hope that it will be useful, but
-// WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-// General Public License for more details.
+// This file is part of FNA (Frescor Network Adaptation)
//
-// You should have received a copy of the GNU General Public License
-// distributed with FRSH API; see file COPYING. If not, write to the
-// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
-// 02111-1307, USA.
+// FNA is free software; you can redistribute it and/or modify it
+// under terms of the GNU General Public License as published by the
+// Free Software Foundation; either version 2, or (at your option) any
+// later version. FNA is distributed in the hope that it will be
+// useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details. You should have received a
+// copy of the GNU General Public License along with FNA; see file
+// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
+// Cambridge, MA 02139, USA.
//
-// As a special exception, if you include this header file into source
-// files to be compiled, this header file does not by itself cause
-// the resulting executable to be covered by the GNU General Public
-// License. This exception does not however invalidate any other
-// reasons why the executable file might be covered by the GNU General
-// Public License.
+// As a special exception, including FNA header files in a file,
+// instantiating FNA generics or templates, or linking other files
+// with FNA objects to produce an executable application, does not
+// by itself cause the resulting executable application to be covered
+// by the GNU General Public License. This exception does not
+// however invalidate any other reasons why the executable file might be
+// covered by the GNU Public License.
// -----------------------------------------------------------------------
//==============================================
#ifndef _FNA_H_
#define _FNA_H_
-#include "frsh_core_types.h" /* for frsh_resource_id_t, frsh_contract_t, etc */
-#include "fna_error.h" /* for ERROR constants */
-#include <stdint.h> /* for uint32_t, UINT32_MAX */
+/* for frsh_resource_id_t, frsh_contract_t, for frsh_network_address_t,
+ frsh_stream_id_t, ... */
+#include "frsh.h"
+/* for timespec */
+#include <time.h>
+/* for ERROR constants */
+// #include "fna_error.h"
+/* for uint32_t, UINT32_MAX */
+#include <stdint.h>
/**
* @defgroup fna FNA Private Interface
*
**/
+
//////////////////////////////////////////////////////////////////////
// INITIALIZATION
//////////////////////////////////////////////////////////////////////
* could be able to handle several networks at the same time)
*
* @return
- * FNA_NO_ERROR \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_RESOURCE_ID_INVALID: if we are not in charge of resource_id \n
* FNA_ERR_ALREADY_INITIALIZED:
* if the function has already been called before (with success) \n
*
**/
-int fna_init(const frsh_resource_id_t resource_id);
+typedef int fna_init_t(const frsh_resource_id_t resource_id);
/*@}*/
/**
* fna_vres_id_t
*
- * Internal virtual resource id. The type fna_vres_id_t is a pointer to void.
- * The FRSH layer will keep a map between the frsh_vres_id_t, this
- * pointer and the resource_id. This pointer could be used as the ID
- * itself using casting, or as internal pointer to any structure.
+ * Internal virtual resource id. In the current implementation it is a 16 bits
+ * value (up to 65536 vres) so it can be integrated easily with the
+ * frsh_vres_id_t type (see frsh_internal_data.h)
*
**/
-typedef void *fna_vres_id_t;
+typedef uint16_t 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
* @param[out] vres The internal virtual resource id
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors (in this case it also means contract accepted) \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_TOO_MANY_VRES: if there is no space for more vres \n
* FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
* 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);
+typedef int fna_contract_negotiate_t
+ (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
* @param[in] new_contract The new contract
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors (in this case it also means contract accepted) \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
* 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);
+typedef int fna_contract_renegotiate_sync_t
+ (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
* This parameter will be ignored if signal_to_notify == FRSH_NULL_SIGNAL.
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_CONTRACT_ID_ALREADY_EXISTS: contract_id is not unique \n
* 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);
+typedef int fna_contract_renegotiate_async_t
+ (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()
* FRSH_RS_NOT_REQUESTED)
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-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);
+typedef int fna_vres_get_renegotiation_status_t
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ frsh_renegotiation_status_t *renegotiation_status);
/**
* fna_vres_destroy()
* @param[in] vres The internal virtual resource id to destroy
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_vres_destroy
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres);
+typedef int fna_vres_destroy_t
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres);
/**
* fna_vres_get_contract()
* @param[out] contract The contract parameters that we want
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_vres_get_contract
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- frsh_contract_t *contract);
+typedef int fna_vres_get_contract_t
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ frsh_contract_t *contract);
/**
* fna_vres_get_usage()
* @param[out] usage Execution time spent by this vres
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_vres_get_usage
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- struct timespec *usage);
+typedef int fna_vres_get_usage_t
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *usage);
/**
* fna_vres_get_remaining_budget()
* @param[out] remaining_budget The remaining budget for this period
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
*
**/
-int fna_vres_get_remaining_budget
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- struct timespec *remaining_budget);
+typedef int fna_vres_get_remaining_budget_t
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *remaining_budget);
/**
* fna_vres_get_budget_and_period()
* @param[out] period The period associated to vres
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* FNA_ERR_BAD_ARGUMENT: if both pointers are NULL \n
*
**/
-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);
+typedef int fna_vres_get_budget_and_period_t
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ struct timespec *budget,
+ struct timespec *period);
/*@}*/
**/
/**
- * fna_spare_get_capacity()
+ * fna_resource_get_capacity()
*
* This operation gets the spare capacity currently assigned to a importance
* level. If we divide this value by UINT32_MAX we will get the network
* @param[out] capacity The spare capacity for that importance level
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \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_spare_get_capacity
- (const frsh_resource_id_t resource_id,
- const int importance,
- uint32_t *capacity);
+typedef int fna_resource_get_capacity_t
+ (const frsh_resource_id_t resource_id,
+ const int importance,
+ uint32_t *capacity);
/**
- * fna_spare_get_total_weight()
+ * fna_resource_get_total_weight()
*
* This function gets the sum of the weight parameters for all vres in a
* network of an importance level.
* @param[out] total_weight The total weight for that importance level
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \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_spare_get_total_weight
- (const frsh_resource_id_t resource_id,
- const int importance,
- int *total_weight);
+typedef int fna_resource_get_total_weight_t
+ (const frsh_resource_id_t resource_id,
+ const int importance,
+ int *total_weight);
/**
- * fna_spare_release_capacity()
+ * fna_vres_decrease_capacity()
*
* This function allows to ask for less budget and period than what we
* received. The request must be compatible with the rest of contract
* @param[in] new_period The new Period
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_CONTRACTED_VRES: if the vres is not contracted \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* contract \n
*
**/
-int fna_spare_release_capacity
- (const frsh_resource_id_t resource_id,
- const fna_vres_id_t vres,
- const struct timespec new_budget,
- const struct timespec new_period);
+typedef int fna_vres_decrease_capacity_t
+ (const frsh_resource_id_t resource_id,
+ const fna_vres_id_t vres,
+ const struct timespec new_budget,
+ const struct timespec new_period);
/*@}*/
* @{
**/
+typedef enum {
+ FRSH_SEND_ENDPOINT_TYPE,
+ FRSH_RECEIVE_ENDPOINT_TYPE
+} frsh_endpoint_type_t;
+
+typedef struct {
+ frsh_endpoint_type_t endpoint_type; // send_endpoint or receive_endpoint
+ fna_vres_id_t vres; // only for send_endpoints
+ bool is_bound; // only for send_endpoints
+ frsh_network_address_t destination; // only for send_endpoints
+ frsh_resource_id_t resource_id;
+ frsh_stream_id_t stream_id;
+ frsh_protocol_info_t protocol_info;
+ frsh_endpoint_queueing_info_t queue_info;
+ union {
+ frsh_send_endpoint_protocol_info_t send;
+ frsh_receive_endpoint_protocol_info_t receive;
+ } endpoint_protocol_info;
+} fna_endpoint_data_t;
+
/**
* fna_send_sync()
*
* @param[in] size The size in bytes of the message
*
* @returns
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* the queue is full (and does not have the policy FNA_QP_OLDEST) \n
*
**/
-int fna_send_sync
- (const frsh_send_endpoint_t *endpoint,
- const void *msg,
- const size_t size);
+typedef int fna_send_sync_t
+ (const fna_endpoint_data_t *endpoint,
+ const void *msg,
+ const size_t size);
/**
* fna_send_async()
* @param[in] size The size in bytes of the message
*
* @returns
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \n
* FNA_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
* FNA_ERR_NOT_BOUND: if endpoint is not bound to a valid vres \n
* FNA_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
* the queue is full (and does not have the policy FNA_QP_OLDEST) \n
*
**/
-int fna_send_async
- (const frsh_send_endpoint_t *endpoint,
- const void *msg,
- const size_t size);
+typedef int fna_send_async_t
+ (const fna_endpoint_data_t *endpoint,
+ const void *msg,
+ const size_t size);
/**
* fna_receive_sync()
* @param[out] buffer Buffer for storing the received message
* @param[in] buffer_size The size in bytes of this buffer
* @param[out] received_bytes The actual number of received bytes
+ * @param[out] from Address of the sender node
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \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
* provided buffer. \n
*
**/
-int fna_receive_sync
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
- const size_t buffer_size,
- size_t *received_bytes);
+typedef int fna_receive_sync_t
+ (const fna_endpoint_data_t *endpoint,
+ void *buffer,
+ const size_t buffer_size,
+ size_t *received_bytes,
+ frsh_network_address_t *from);
/**
* fna_receive_async()
* @param[out] buffer Buffer for storing the received message
* @param[in] buffer_size The size in bytes of this buffer
* @param[out] received_bytes The actual number of received bytes
+ * @param[out] from Address of the sender node
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \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_NO_MESSAGE: if no messages are available in the queue. \n
*
**/
-int fna_receive_async
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
- const size_t buffer_size,
- size_t *received_bytes);
+typedef int fna_receive_async_t
+ (const fna_endpoint_data_t *endpoint,
+ void *buffer,
+ const size_t buffer_size,
+ size_t *received_bytes,
+ frsh_network_address_t *from);
/**
- * fna_send_endpoint_get_pending_messages()
+ * fna_send_endpoint_get_status()
*
- * This function tells the number of messages still pending
+ * This function tells the number of messages still pending in the
+ * endpoint queue, whether the network is up or down with some
+ * optional information which is protocol_dependent.
*
* @param[in] endpoint The send endpoint (resource_id is in the endpoint).
* @param[out] number_of_pending_messages The number of pending messages
+ * @param[out] network_status How is the network (up, down..)
+ * @param[out] protocol_status Protocol dependent status info
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \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_send_endpoint_get_pending_messages
- (const frsh_send_endpoint_t *endpoint,
- int *number_of_pending_messages);
+typedef int fna_send_endpoint_get_status_t
+ (const fna_endpoint_data_t *endpoint,
+ int *number_of_pending_messages,
+ frsh_endpoint_network_status_t *network_status,
+ frsh_protocol_status_t *protocol_status);
+
+/**
+ * fna_receive_endpoint_create_callback()
+ *
+ * This operation is a called from frsh_receive_endpoint_create with a
+ * receive_endpoint structure already filled.
+ *
+ * Receiving endpoints are not bound to any network vres, this is
+ * because don't originate any traffic.
+ *
+ * @param[in] endpoint the endpoint object.
+ *
+ * @return
+ * 0 if there are no errors \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
+ **/
+typedef int fna_receive_endpoint_create_callback_t
+ (fna_endpoint_data_t *endpoint);
/**
* fna_receive_endpoint_get_pending_messages
*
* This function tells the number of messages still pending in the
- * receive endpoint queue
+ * endpoint queue, whether the network is up or down and some optional
+ * information which is protocol dependent.
*
* @param[in] endpoint The receive endpoint (resource_id is in the endpoint).
* @param[out] number_of_pending_messages The number of pending messages
+ * @param[out] network_status How is the network (up, down..)
+ * @param[out] protocol_status Protocol dependent status info
*
* @return
- * FNA_NO_ERROR: in this case it also means contract accepted \n
+ * 0 if there are no errors \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_receive_endpoint_get_pending_messages
- (const frsh_receive_endpoint_t *endpoint,
- int *number_of_pending_messages);
+typedef int fna_receive_endpoint_get_status_t
+ (const fna_endpoint_data_t *endpoint,
+ int *number_of_pending_messages,
+ frsh_endpoint_network_status_t *network_status,
+ frsh_protocol_status_t *protocol_status);
/*@}*/
**/
/**
- * fna_message_get_tx_time()
+ * fna_network_get_max_message_size()
*
- * This operation gives the worst case transmission time that it takes to
- * send a message of the nbytes size through the network designated by
- * resource_id, 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.
+ * 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.
*
* @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 (including 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
+ * 0 if there are no errors \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_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
+ * invalid \n
*
**/
-int fna_message_get_tx_time
- (const frsh_resource_id_t resource_id,
- const size_t nbytes,
- struct timespec *tx_time);
+typedef int fna_network_get_max_message_size_t
+ (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 are
+ * considered 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
+ * 0 if there are no errors \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 resource id does not represent
+ * a network accessible from the current processing node \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
+ * than zero \n
+ *
+ **/
+typedef int fna_network_bytes_to_budget_t
+ (const frsh_resource_id_t resource_id,
+ const size_t nbytes,
+ frsh_rel_time_t *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
+ * 0 if there are no errors \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_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
+ * an invalid time value \n
*
**/
-int fna_message_get_max_size
- (const frsh_resource_id_t *resource_id,
- size_t *max_size);
+typedef int fna_network_budget_to_bytes_t
+ (const frsh_resource_id_t resource_id,
+ const frsh_rel_time_t *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
+ * 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
+ * 0 if there are no errors \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 resource id does not represent
+ * a network accessible from the current processing node \n
+ * FNA_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+typedef int fna_network_get_min_effective_budget_t
+ (const frsh_resource_id_t resource_id,
+ frsh_rel_time_t *budget);
/*@}*/
+typedef struct {
+ fna_init_t *fna_init;
+ fna_contract_negotiate_t *fna_contract_negotiate;
+ fna_contract_renegotiate_sync_t *fna_contract_renegotiate_sync;
+ fna_contract_renegotiate_async_t *fna_contract_renegotiate_async;
+ fna_vres_get_renegotiation_status_t *fna_vres_get_renegotiation_status;
+ fna_vres_destroy_t *fna_vres_destroy;
+ fna_vres_get_contract_t *fna_vres_get_contract;
+ fna_vres_get_usage_t *fna_vres_get_usage;
+ fna_vres_get_remaining_budget_t *fna_vres_get_remaining_budget;
+ fna_vres_get_budget_and_period_t *fna_vres_get_budget_and_period;
+ fna_resource_get_capacity_t *fna_resource_get_capacity;
+ fna_resource_get_total_weight_t *fna_resource_get_total_weight;
+ fna_vres_decrease_capacity_t *fna_vres_decrease_capacity;
+ fna_send_sync_t *fna_send_sync;
+ fna_send_async_t *fna_send_async;
+ fna_receive_sync_t *fna_receive_sync;
+ fna_receive_async_t *fna_receive_async;
+ fna_send_endpoint_get_status_t *fna_send_endpoint_get_status;
+ fna_receive_endpoint_create_callback_t *fna_receive_endpoint_created;
+ fna_receive_endpoint_get_status_t *fna_receive_endpoint_get_status;
+ fna_network_get_max_message_size_t *fna_network_get_max_message_size;
+ fna_network_bytes_to_budget_t *fna_network_bytes_to_budget;
+ fna_network_budget_to_bytes_t *fna_network_budget_to_bytes;
+ fna_network_get_min_effective_budget_t *fna_network_get_min_eff_budget;
+} fna_operations_t;
+
#endif // _FNA_H_
projects / frescor / fna.git / blobdiff