#ifndef _FRSH_DISTRIBUTED_H_
#define _FRSH_DISTRIBUTED_H_
-
/**
* @file frsh_distributed.h
**/
* This module defines the functions and typedefs for use in
* distributed applications.
*
- * Each network is identified by its network_id and FRSH hides its
+ * 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.
*
*
* 1. Map (internally in FRSH implementation)
* - node--> network_addresses
- * - network --> network_id's
+ * - network --> resource_id's
* - unidirectional communication channel --> stream_id
* - other config --> protocol_info.
*
* - Other protocol dependent function in protocol_contract_info.
* 2.2. Create a send_endpoint per any unidirectional stream that will
* be used in sending
- * network_id --> the network through which the stream will
+ * 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.
* and the network contract will be canceled.
**/
-
-#define FRSH_DISTRIBUTED_MODULE_SUPPORTED 1
+/**
+ * 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
*
* We get protocol info from the contract
**/
-int frsh_contract_get_protocol_info(frsh_contract_t 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
* through which, after the corresponding binding, it is possible to
* send data to a unicast or multicast destination.
*
- * @param[in] network_id Identifier of the network referred in the
+ * @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[out] endpoint Placeholder for the endpoint object.
**/
int frsh_send_endpoint_create
- (frsh_resource_id_t network_id,
- frsh_network_address_t destination,
- frsh_stream_id_t stream_id,
- frsh_send_endpoint_t *endpoint);
+ (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()
* endpoint at creation time.
**/
int frsh_send_endpoint_get_params
- (const frsh_send_endpoint_t *endpoint,
- frsh_resource_id_t *network_id,
+ (const frsh_send_endpoint_t endpoint,
+ frsh_resource_id_t *resource_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()
* code.
**/
int frsh_send_endpoint_destroy
- (frsh_send_endpoint_t *endpoint);
+ (frsh_send_endpoint_t endpoint);
/**
* 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 network_id specified at
+ * A consistency check is done in which the resource_id specified at
* endpoint creation must correspond to the resource_id of the vres
* contract.
*
**/
int frsh_send_endpoint_bind
(frsh_vres_id_t vres,
- frsh_send_endpoint_t *endpoint);
+ frsh_send_endpoint_t endpoint);
/**
* frsh_send_endpoint_unbind()
* FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
**/
int frsh_send_endpoint_unbind
- (frsh_send_endpoint_t *endpoint);
+ (frsh_send_endpoint_t endpoint);
/**
* frsh_send_endpoint_get_vres_id()
* is NULL \n
**/
int frsh_send_endpoint_get_vres_id
- (const frsh_send_endpoint_t *endpoint,
+ (const frsh_send_endpoint_t endpoint,
frsh_vres_id_t *vres);
/**
* have the policy FRSH_QP_OLDEST \n
**/
int frsh_send_async
- (const frsh_send_endpoint_t *endpoint,
- void *msg,
- size_t size);
+ (const frsh_send_endpoint_t endpoint,
+ const void *msg,
+ const size_t size);
/**
* frsh_send_sync()
* until the message is processed.
**/
int frsh_send_sync
- (const frsh_send_endpoint_t *endpoint,
+ (const frsh_send_endpoint_t endpoint,
void *msg,
size_t size);
-
-
/**
* frsh_send_endpoint_get_status()
*
* 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 *network_status,
- frsh_protocol_status_t *protocol_status);
+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()
* 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 network_id.
+ * it can be determined internally by FRSH based on the resource_id.
*
* Note also that messages may come from diferent originators.
*
- * @param[in] network_id Id of the network from which we listen.
+ * @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).
* valid \n
**/
int frsh_receive_endpoint_create
- (frsh_resource_id_t network_id,
+ (frsh_resource_id_t resource_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 *resource_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()
* code.
**/
int frsh_receive_endpoint_destroy
- (frsh_receive_endpoint_t *endpoint);
+ (frsh_receive_endpoint_t endpoint);
/**
* provided buffer \n
**/
int frsh_receive_sync
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
+ (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()
* provided buffer \n
**/
int frsh_receive_async
- (const frsh_receive_endpoint_t *endpoint,
- void *buffer,
+ (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);
/**
* 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 *network_status,
- frsh_protocol_status_t *protocol_status);
-
-
+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