// -----------------------------------------------------------------------
-// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politécnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// Visual Tools S.A. SPAIN
+// Rapita Systems Ltd UK
+// Evidence ITALY
+//
+// See http://www.frescor.org for a link to partners' websites
+//
+// 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.
+//
+//
+// based on previous work (FSF) done in the FIRST project
+//
+// Copyright (C) 2005 Mälardalen University, SWEDEN
// Scuola Superiore S.Anna, ITALY
// Universidad de Cantabria, SPAIN
// University of York, UK
//
-// FRSH API web pages: http://marte.unican.es/frsh/docs/
+// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
// This file is part of FRSH API
// Public License.
// -----------------------------------------------------------------------
//frsh_distributed.h
-//=====================================================================
-// FFFFFFIII RRRRR SSTTTTTTT
-// FF IIR RR SS
-// FF IR SS
-// FFFFFF RRRR SSSSST
-// FF FI RRR SS
-// FF II RRR SS
-// FF IIIIIR RS
+//==============================================
+// ******** ******* ******** ** **
+// **///// /**////** **////// /** /**
+// ** /** /** /** /** /**
+// ******* /******* /********* /**********
+// **//// /**///** ////////** /**//////**
+// ** /** //** /** /** /**
+// ** /** //** ******** /** /**
+// // // // //////// // //
//
-// FRSH(FIRST Scheduling Framework)
-// distributed services functionality
-//=====================================================================
-
-#include "frsh_core.h"
-
+// FRSH(FRescor ScHeduler), pronounced "fresh"
+//==============================================
#ifndef _FRSH_DISTRIBUTED_H_
#define _FRSH_DISTRIBUTED_H_
-#define FRSH_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
-//FRSH_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 FRSH_ERR_BAD_ARGUMENT
-//if contract is null or the network id is not
-//valid.
-
-int
-frsh_set_contract_network_id
- (frsh_contract_parameters_t *contract,
- frsh_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 FRSH_NULL_NETWORK_ID constant instead.
-//it returns 0 if successful, or
-//FRSH_ERR_BAD_ARGUMENT if any of the pointers is
-//null.
-
-int
-frsh_get_contract_network_id
- (const frsh_contract_parameters_t *contract,
- frsh_network_id_t *network_id);
-
-//Transmission services:
-
-//opaque types for frsh endpoints
-typedef FRSH_SEND_ENDPOINT_T_OPAQUE frsh_send_endpoint_t;
-typedef FRSH_RECEIVE_ENDPOINT_T_OPAQUE frsh_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
-typedef unsigned int frsh_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
-typedef unsigned int frsh_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 FRSH_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
-frsh_create_send_endpoint
- (frsh_network_id_t network_id,
- frsh_node_address_t receiver,
- frsh_port_t port,
- frsh_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 FRSH_ERR_BAD_ARGUMENT if the endpoint is not
-//valid.
-int
-frsh_destroy_send_endpoint
- (frsh_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
-//FRSH_ERR_BAD_ARGUMENT if the endpoint is not
-//valid or all the other pointers are NULL.
-int
-frsh_get_send_endpoint_parameters
- (const frsh_send_endpoint_t *endpoint,
- frsh_network_id_t *network_id,
- frsh_node_address_t *receiver,
- frsh_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
-//FRSH_ERR_BAD_ARGUMENT if the endpoint or the server
-//are not valid, it also fails with a
-//value of FRSH_ERR_ALREADY_BOUND if the server is
-//already bound to some other send endpoint.
-//It fails with FRSH_ERR_WRONG_NETWORK if the server
-//network id is not the same as the one in the endpoint
-int
-frsh_bind_endpoint_to_server
- (frsh_server_id_t server,
- frsh_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
-//FRSH_ERR_NOT_BOUND if the endpoint has no server
-//bound
-int
-frsh_unbind_endpoint_from_server
- (frsh_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 FRSH_ERR_BAD_ARGUMENT if the
-//endpoint is not valid or server is NULL
-int
-frsh_get_endpoint_server
- (const frsh_send_endpoint_t *endpoint,
- frsh_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 frsh 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 FRSH_ERR_BAD_ARGUMENT if endpoint is not valid; it fails
-//with FRSH_ERR_NOT_BOUND is not bound to a valid server; it fails with
-//FRSH_ERR_TOO_LARGE if the message is too large for the network
-//protocol; it fails with FRSH_ERR_BUFFER_FULL if the sending queue is
-//full
-int
-frsh_send
- (const frsh_send_endpoint_t *endpoint,
+/**
+ * @file frsh_distributed.h
+ **/
+
+
+#include "frsh_distributed_types.h"
+#include "frsh_core_types.h"
+
+/**
+ * @defgroup distributed Distributed module
+ *
+ * This module defines the functions and typedefs for use in
+ * distributed applications.
+ *
+ * Each network is identified by its resource_id and FRSH hides its
+ * characteristics completely. The type of network is implied with
+ * its ID via a configuration table defined at compile time.
+ *
+ * FRSH uses the "message" as the atomic unit for every exchange.
+ * Queue sizes are measured in number of pending messages.
+ *
+ * FRSH provides a function to calculate the transmision time needed
+ * for a certain message size in a network as well as the maximum
+ * message size that can admit.
+ *
+ * Note also that package delivery guarantee is protocol dependent.
+ * For protocols in which the order is no guaranteed, the application
+ * needs to add extra info to detect possible package disorder.
+ *
+ * Summary of typical steps.
+ *
+ * 1. Map (internally in FRSH implementation)
+ * - node--> network_addresses
+ * - network --> resource_id's
+ * - unidirectional communication channel --> stream_id
+ * - other config --> protocol_info.
+ *
+ * 2. In a sending node:
+ * 2.1. Negotiates a "network contract" per communication channel
+ * that is used in the application. In the contract it is
+ * specified:
+ * - frsh_resource_type = FRSH_RT_NETWORK.
+ * - frsh_resource_id = <network id #>
+ * - budget: Time needed to send the required data per period.
+ * (you can use frsh_netinfo_*() functions for this).
+ * - period: Period of sendings.
+ * - Queueing info: How will sends be queued at sendEndpoint.
+ * - Other protocol dependent function in protocol_contract_info.
+ * 2.2. Create a send_endpoint per any unidirectional stream that will
+ * be used in sending
+ * resource_id --> the network through which the stream will
+ * flow (this is extra info needed for coherency
+ * with the bind).
+ * destinator --> network_address of the destination.
+ * stream_id --> the unidirectional communication channel.
+ * 2.3. Bind the send_endpoint to the network contract negotiated
+ * above.
+ * 2.4. The (processor) sending vres invokes frsh_send_(a)sync() to
+ * send the data through the corresponding stream.
+ *
+ * 3. In a receiving node:
+ * 3.1. Create a receive_endpoint per any unidirectional stream
+ * that will be used in receiving.
+ * 3.2. The processor expecting a reception of message invokes
+ * frsh_receive_(a)sync() to read the incoming data.
+ *
+ * 4. When all comunication is finished and the channel is no longer
+ * needed the nodes will destroy the send and receive endpoints
+ * and the network contract will be canceled.
+ **/
+
+/**
+ * frsh_distributed_init(void)
+ *
+ * This operation initializes all the installed networks and the structures
+ * that are necessary for the distributed module. Currently it is called by
+ * frsh_init so it is not necessary that the user calls it again.
+ *
+ * 0: No error \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ *
+ **/
+int frsh_distributed_init(void);
+
+//////////////////////////////////////////////////////////////////////
+// CONTRACT ASPECTS
+//////////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup distcontract Contract Info for Distributed Systems
+ * @ingroup distributed
+ *
+ * These functions help you calculate the needed budget for network
+ * contracts and also to include protocol dependent info in contract
+ * parameters.
+ *
+ * @{
+ **/
+
+/**
+ * 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.
+ *
+ * @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_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_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
+ * 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_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()
+ *
+ * This function adds queueing parameters that will be used in the
+ * sendEndpoint when the sendEndpoint is bound to the vres.
+ **/
+int frsh_contract_set_queueing_info(frsh_endpoint_queueing_info_t queueing_info,
+ frsh_contract_t *contract);
+
+/**
+ * frsh_contract_get_queueing_info()
+ *
+ * This function gets the queueing parameters that were specified in
+ * the network contract.
+ **/
+int frsh_contract_get_queueing_info(const frsh_contract_t *contract,
+ frsh_endpoint_queueing_info_t *queueing_info);
+
+/**
+ * frsh_contract_set_protocol_info
+ *
+ * We add protocol info to the contract
+ **/
+int frsh_contract_set_protocol_info(frsh_protocol_info_t protocol_info,
+ frsh_contract_t *contract);
+
+/**
+ * frsh_contract_get_protocol_info
+ *
+ * We get protocol info from the contract
+ **/
+int frsh_contract_get_protocol_info(frsh_contract_t *contract,
+ frsh_protocol_info_t *protocol_info);
+
+/**
+ * frsh_contract_marshal
+ *
+ * Convert a contract to a sequence of bytes of minimum size so it can
+ * be sent through the network with the minimum amount of bytes.
+ *
+ **/
+
+int frsh_contract_marshal(const frsh_contract_t *contract,
+ unsigned char *buffer,
+ const size_t buffer_size,
+ size_t *size);
+
+/**
+ * frsh_contract_unmarshal
+ *
+ * Convert a sequence of bytes generated by frsh_contract_marshal to a contract
+ *
+ **/
+
+int frsh_contract_unmarshal(frsh_contract_t *contract,
+ const unsigned char *marshal_bytes,
+ const size_t size);
+
+/*@}*/
+//////////////////////////////////////////////////////////////////////
+// TWO STEP NEGOTIATION
+//////////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup twostepnego Two Step Negotiation
+ * @ingroup distributed
+ *
+ * Using the core services of FRSH, contracts may be negotiated in a
+ * single step.
+ *
+ * An alternative two-step negotiation process is introduced in the
+ * distribution module: the first step involves the reservation of the
+ * resources, but without the right to use them, and the second step
+ * is the commitment to use those resources.
+ *
+ * The rationale behind this approach is that in distributed systems,
+ * when a distributed transaction is being negotiated the system
+ * should only commit the virtual resources that were negotiated with
+ * various nodes in the system if the results of all negotiations
+ * match together. This approach enhances the efficiency since the
+ * actual temporal values of the virtual resources on distributed
+ * nodes are only changed if the initiator of the distributed
+ * transaction is satisfied with the results of the negotiations.
+ *
+ * After the reservation, it is not necessary to change the actual
+ * virtual resource attributes (and modifying the schedule) on each
+ * node before the initiator of the distributed transaction knows the
+ * amount of available virtual resources. A renegotiation of a
+ * reserved virtual resource is possible, to harmonize for the
+ * available virtual resources in other parts of the system, before a
+ * final commitment is made.
+ *
+ * @{
+ **/
+
+
+/**
+ * frsh_contract_negotiate_reservation()
+ *
+ * Negotiate a service contract, obtaining a virtual resource id that
+ * represents a reservation of resources, but without the right to use
+ * those resources until the reservation is committed via
+ * frsh_vres_commit_reservation. In particular, this virtual resource
+ * cannot be bound until committed, but renegotiations are allowed for
+ * it.
+ */
+int frsh_contract_negotiate_reservation
+ (const frsh_contract_t *contract,
+ frsh_vres_id_t *vres);
+
+/**
+ * frsh_vres_commit_reservation()
+ *
+ * Commit the resources reserved for a virtual resource through a
+ * frsh_contract_negotiate_reservation operation. The effects of
+ * subsequent calls to frsh_contract_negotiate_reservation and
+ * frsh_vres_commit_reservation are equivalent to a single call to
+ * frsh_contract_negotiate.
+ */
+int frsh_vres_commit_reservation
+ (const frsh_vres_id_t vres);
+
+/* @} */
+
+
+
+//////////////////////////////////////////////////////////////////////
+// TRANSMISSION SERVICES
+//////////////////////////////////////////////////////////////////////
+
+/**
+ * @defgroup txservices Transmission services
+ * @ingroup distributed
+ *
+ * These functions allow to create and manage endpoints for sending
+ * and receiving and to perform send and receive operations both
+ * synchronously (blocking) and asynchronously (non-blocking).
+ *
+ * @{
+ **/
+
+
+/**
+ * frsh_send_endpoint_create()
+ *
+ * This operation creates a unidirectional stream input endpoint
+ * through which, after the corresponding binding, it is possible to
+ * send data to a unicast or multicast destination.
+ *
+ * @param[in] resource_id Identifier of the network referred in the
+ * network contract as a resource_id.
+ * @param[in] destination FRSH abstraction of the protocol address for the
+ * destinator node.
+ * @param[in] stream_id Identifier of the communication channel between
+ * the nodes. Multiplexing is achieved by using
+ * different streams between the same nodes and the
+ * same network.
+ * @param[in] queueing_info Queueing params of the endpoint (size and
+ * policy).
+ * @param[in] protocol_info Optional protocol-dependent info.
+ * @param[out] endpoint Placeholder for the endpoint object.
+ **/
+int frsh_send_endpoint_create
+ (frsh_resource_id_t resource_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);
+
+/**
+ * frsh_send_endpoint_get_params()
+ *
+ * This operation returns in the variables associated to the
+ * endpoint at creation time.
+ **/
+int frsh_send_endpoint_get_params
+ (const frsh_send_endpoint_t endpoint,
+ frsh_resource_id_t *resource_id,
+ frsh_network_address_t *destination,
+ frsh_stream_id_t *stream,
+ frsh_send_endpoint_protocol_info_t *protocol_info);
+
+/**
+ * frsh_send_endpoint_destroy()
+ *
+ * This operation eliminates any resources reserved for the referenced
+ * endpoint. Pending messages will be discarded and processor-vres
+ * waiting in a synchronous operation will be awoken with an error
+ * code.
+ **/
+int frsh_send_endpoint_destroy
+ (frsh_send_endpoint_t endpoint);
+
+
+/**
+ * frsh_send_endpoint_bind()
+ *
+ * This operation associates a send endpoint with a network vres,
+ * which means that messages sent through this endpoint will consume
+ * the vres's reserved bandwidth and its packets will be sent
+ * according to the contract established for that vres.
+ *
+ * If the endpoint is already bound to another vres, it is effectively
+ * unbound from it and bound to the specified one. However if a vres
+ * is already bound to another endpoint an error is returned.
+ *
+ * A consistency check is done in which the resource_id specified at
+ * endpoint creation must correspond to the resource_id of the vres
+ * contract.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if the endpoint or the vres are not
+ * valid \n
+ * FRSH_ERR_ALREADY_BOUND if the vres is already bound to some
+ * other send endpoint \n
+ * FRSH_ERR_WRONG_NETWORK if the vres network id is not the same
+ * as the one in the endpoint \n
+ **/
+int frsh_send_endpoint_bind
+ (frsh_vres_id_t vres,
+ frsh_send_endpoint_t endpoint);
+
+/**
+ * frsh_send_endpoint_unbind()
+ *
+ * This operation unbinds a send endpoint from a vres. Endpoints with
+ * 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 \n
+ * FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
+ **/
+int frsh_send_endpoint_unbind
+ (frsh_send_endpoint_t endpoint);
+
+/**
+ * frsh_send_endpoint_get_vres_id()
+ *
+ * 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 \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 \n
+ **/
+int frsh_send_endpoint_get_vres_id
+ (const frsh_send_endpoint_t endpoint,
+ frsh_vres_id_t *vres);
+
+/**
+ * frsh_send_async()
+ *
+ * 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 frsh service will schedule the sending of messages and
+ * implement the communications sporadic vres corresponding to the
+ * network vres bound to the given endpoint.
+ *
+ * @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 \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 \n
+ **/
+int frsh_send_async
+ (const frsh_send_endpoint_t endpoint,
+ const void *msg,
+ const size_t size);
+
+/**
+ * frsh_send_sync()
+ *
+ * Similar to previous function but now the sending vres gets blocked
+ * until the message is processed.
+ **/
+int frsh_send_sync
+ (const frsh_send_endpoint_t endpoint,
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
-//FRSH_ERR_BAD_ARGUMENT if the port or the network id are not valid.
-int
-frsh_create_receive_endpoint
- (frsh_network_id_t network_id,
- frsh_port_t port,
+/**
+ * frsh_send_endpoint_get_status()
+ *
+ * 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.
+ **/
+int frsh_send_endpoint_get_status
+ (const frsh_send_endpoint_t endpoint,
+ int *number_pending_msg,
+ frsh_endpoint_network_status_t *network_status,
+ frsh_protocol_status_t *protocol_status);
+
+/**
+ * frsh_receive_endpoint_create()
+ *
+ * This operation creates a receive endpoint associated with a
+ * undirectional stream within a network interface of the node.
+ *
+ * Receiving endpoints are not bound to any network vres, this is
+ * because don't originate any traffic.
+ *
+ * Note that the protocol address is not needed for reception because
+ * it can be determined internally by FRSH based on the resource_id.
+ *
+ * Note also that messages may come from diferent originators.
+ *
+ * @param[in] resource_id Id of the network from which we listen.
+ * @param[in] stream_id Id of the stream within the network.
+ * @param[in] queueing_info Buffering information(queue size and
+ * policy).
+ * @param[in] protocol_info Extra protocol info opaque for the
+ * application.
+ * @param[in] endpoin Placeholder for the endpoint object.
+ *
+ * @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 resource_id,
+ frsh_stream_id_t stream_id,
+ frsh_endpoint_queueing_info_t queueing_info,
+ frsh_receive_endpoint_protocol_info_t protocol_info,
frsh_receive_endpoint_t *endpoint);
-//This operation eliminates any resources reserved
-//for the referenced endpoint. it
-//can not be further used to invoke receive
-//operations on it.It returns 0 if successful, but it fails with
-//FRSH_ERR_BAD_ARGUMENT if endpoint is NULL or not valid.
-int
-frsh_destroy_receive_endpoint
- (frsh_receive_endpoint_t *endpoint);
-
-//This operation returns in the variables the_network_id,
-//and port, the corresponding
-//parameters used in the creation of the given
-//receive endpoint. It returns 0 if successful, but it fails with
-//FRSH_ERR_BAD_ARGUMENT if endpoint is NULL or not valid or network_id
-//or port are NULL
-
-int
-frsh_get_receive_endpoint_parameters
- (frsh_receive_endpoint_t *endpoint,
- frsh_network_id_t *the_network_id,
- frsh_port_t *the_port);
-
-//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
-//FRSH_ERR_NO_SPACE if the buffersize is too small for the message
-//received (in which case the message is lost), or with
-//FRSH_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
-frsh_receive
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
- size_t buffersize,
- size_t *messagesize);
-
-//This operation is the same as frsh_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
-//FRSH_ERR_NO_MESSAGES
-int
-frsh_try_receive
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
- size_t buffersize,
- size_t *messagesize);
-
-
-
-// Getting configuration dependent information
-
-//This 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. It
-//is used to calculate the minimum and maximum budgets used
-//in the preparation of network contracts. The effective
-//network utilization budget (usually called bandwidth) is
-//always assiged as a number of packets per time unit, so
-//the time used in the negotiation of contracts will be
-//internally transformed into the corresponding necessary
-//number of packets. It returns FRSH_ERR_BAD_ARGUMENT if
-//network_id is not a valid identifier or if budget is a
-//NULL pointer.
-int
-frsh_packet_tx_time
- (frsh_network_id_t network_id,
- struct timespec *budget);
-
-//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 consequently prepare the corresponding
-//contracts. It returns FRSH_ERR_BAD_ARGUMENT if network_id
-//is not a valid identifier or if packet_size is a NULL
-//pointer.
-int
-frsh_packet_size
- (frsh_network_id_t network_id,
- size_t *packet_size);
-
-//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. It
-//returns FRSH_ERR_BAD_ARGUMENT if network_id is not a valid
-//identifier or the pointer max_msg_size is NULL
-int
-frsh_max_message_size
- (frsh_network_id_t network_id,
- size_t *max_msg_size);
-
+/**
+ * frsh_receive_endpoint_get_params()
+ *
+ * This operation returns in the variables associated to the
+ * endpoint at creation time.
+ **/
+int frsh_receive_endpoint_get_params
+ (const frsh_receive_endpoint_t endpoint,
+ frsh_resource_id_t *resource_id,
+ frsh_stream_id_t *stream,
+ frsh_endpoint_queueing_info_t *queueing_info,
+ frsh_receive_endpoint_protocol_info_t *protocol_info);
+
+/**
+ * frsh_receive_endpoint_destroy()
+ *
+ * This operation eliminates any resources reserved for the referenced
+ * endpoint. Pending messages will be discarded and processor-vres
+ * waiting in a synchronous operation will be awoken with an error
+ * code.
+ **/
+int frsh_receive_endpoint_destroy
+ (frsh_receive_endpoint_t endpoint);
+
+
+/**
+ * frsh_receive_sync()
+ *
+ * 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 buffer_size, the function stores it in the variable
+ * pointed to by buffer and puts the number of bytes received in the
+ * variable pointed to by message size.
+ *
+ * The function fails with FRSH_ERR_NO_SPACE if the buffersize is
+ * too small for the message received. In this case the message is
+ * lost.
+ *
+ * Messages arriving at a destination buffer that is full will be
+ * silently discarded (details in the queueing policy of the
+ * endpoint). 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.
+ *
+ * @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 \n
+ **/
+int frsh_receive_sync
+ (const frsh_receive_endpoint_t endpoint,
+ void *buffer,
+ size_t buffer_size,
+ size_t *message_size,
+ frsh_network_address_t *from);
+
+/**
+ * frsh_receive_async()
+ *
+ * This operation is similar to the previous one but it works in a non
+ * blocking (asynchronous) fashion. If no message is available it
+ * returns with error FRSH_NO_MESSAGE.
+ *
+ * @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_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 \n
+ **/
+int frsh_receive_async
+ (const frsh_receive_endpoint_t endpoint,
+ void *buffer,
+ size_t buffer_size,
+ size_t *message_size,
+ frsh_network_address_t *from);
+
+
+/**
+ * frsh_receive_endpoint_get_status
+ *
+ * This function tells the number of messages still pending in the
+ * endpoint queue, whether the network is up or down and some optional
+ * information which is protocol dependent.
+ **/
+int frsh_receive_endpoint_get_status
+ (const frsh_receive_endpoint_t endpoint,
+ int *number_pending_messages,
+ frsh_endpoint_network_status_t *network_status,
+ frsh_protocol_status_t *protocol_status);
+
+/*@}*/
#endif // _FRSH_DISTRIBUTED_H_
projects / frescor / frsh-include.git / blobdiff