Upgrading FRSH trunk to D-AC2v2. Phase I: Moving FRSH-FOSA to FOSA

[frescor/frsh-include.git] / frsh_distributed.h

diff --git a/frsh_distributed.h b/frsh_distributed.h
index 9796c8c0f91ee29101881163b8c466ee3ebfa7a5..bb501e25180e6ff5b4f9bef4ef2c16ca94a25cc5 100644 (file)
--- a/frsh_distributed.h
+++ b/frsh_distributed.h
@@ -316,10 +316,100 @@ int frsh_contract_set_protocol_info(frsh_protocol_info_t protocol_info,
  *
  * 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
@@ -582,10 +672,10 @@ int frsh_receive_endpoint_destroy
  **/
 int frsh_receive_sync
   (const frsh_receive_endpoint_t  endpoint,
-   void                          *buffer,
+   void                           *buffer,
    size_t                         buffer_size,
-   size_t                        *message_size,
-   frsh_network_address_t *from);
+   size_t                         *message_size,
+   frsh_network_address_t         *from);
 
 /**
  * frsh_receive_async()
@@ -603,10 +693,10 @@ int frsh_receive_sync
  **/
 int frsh_receive_async
   (const frsh_receive_endpoint_t  endpoint,
-   void                          *buffer,
+   void                           *buffer,
    size_t                         buffer_size,
-   size_t                        *message_size,
-   frsh_network_address_t *from);
+   size_t                         *message_size,
+   frsh_network_address_t         *from);
 
 
 /**