// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+// Copyright (C) 2006 - 2009 FRESCOR consortium partners:
//
// 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
+// This file is part of FRSH (FRescor ScHeduler)
//
-// 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 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. FRSH 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 FRSH; see file
+// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
+// Cambridge, MA 02139, USA.
//
-// 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.
-//
-// 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.
-//
-// 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 FRSH header files in a file,
+// instantiating FRSH generics or templates, or linking other files
+// with FRSH 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.
// -----------------------------------------------------------------------
//frsh_distributed.h
//==============================================
#ifndef _FRSH_DISTRIBUTED_H_
#define _FRSH_DISTRIBUTED_H_
+
/**
* @file frsh_distributed.h
**/
#include "frsh_distributed_types.h"
#include "frsh_core_types.h"
+FRSH_CPP_BEGIN_DECLS
+
+// this global variable is assigned by frsh_distributed_init()
+extern frsh_resource_id_t THE_FRSH_CPU_ID;
+
+typedef enum {
+ FRSH_NETPF_FRESCAN = 0,
+ FRSH_NETPF_RTEP = 1,
+ FRSH_NETPF_UNIX = 2,
+ FRSH_NETPF_FWP = 3,
+ FRSH_NETPF_CLUSTER_TREE = 4,
+ FRSH_NETPF_ITEM = 5,
+} frsh_netpf_t;
+
/**
* @defgroup distributed Distributed module
*
int frsh_network_bytes_to_budget
(const frsh_resource_id_t resource_id,
const size_t nbytes,
- struct timespec *budget);
+ frsh_rel_time_t *budget);
/**
* frsh_network_budget_to_bytes()
**/
int frsh_network_budget_to_bytes
(const frsh_resource_id_t resource_id,
- const struct timespec *budget,
+ const frsh_rel_time_t *budget,
size_t *nbytes);
/**
**/
int frsh_network_get_min_effective_budget
(const frsh_resource_id_t resource_id,
- struct timespec *budget);
+ frsh_rel_time_t *budget);
/**
* frsh_contract_set_queueing_info()
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
int frsh_send_endpoint_destroy
(frsh_send_endpoint_t endpoint);
-
/**
* frsh_send_endpoint_bind()
*
**/
int frsh_send_sync
(const frsh_send_endpoint_t endpoint,
- void *msg,
+ const void *msg,
size_t size);
/**
**/
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()
**/
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);
/**
/*@}*/
+FRSH_CPP_END_DECLS
+
#endif // _FRSH_DISTRIBUTED_H_
projects / frescor / frsh-include.git / blobdiff