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 58d8d8b9d83a10c9629115d8f297778c7ad967aa..bb501e25180e6ff5b4f9bef4ef2c16ca94a25cc5 100644 (file)
--- a/frsh_distributed.h
+++ b/frsh_distributed.h
@@ -344,6 +344,72 @@ int frsh_contract_unmarshal(frsh_contract_t      *contract,
                             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