// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+// Copyright (C) 2006 - 2009 FRESCOR consortium partners:
//
// Universidad de Cantabria, SPAIN
// University of York, UK
// 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
//
//
// 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
// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
-// This file is part of FRSH API
-//
-// 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 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.
+// This file is part of FRSH (FRescor ScHeduler)
//
-// 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.
+// 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.
//
-// 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_feedback_control.h
#include <time.h>
-#include "frsh_fosa.h"
-#include "frsh_feedback_control_types.h"
+//#include "frsh_feedback_control_types.h"
#include "frsh_core_types.h"
+FRSH_CPP_BEGIN_DECLS
#define FRSH_FEEDBACKCTRL_MODULE_SUPPORTED 1
* This module provides a way to implement a QoS manager at the
* application level.
*
+ * @note
+ * Please, note that, in order to exploit the feedback-scheduling
+ * functionality of FRESCOR, an application needs to use a set of
+ * different functions:
+ * <ul>
+ * <li>the frsh_contract_set_basic_params() and the
+ * frsh_contract_set_reclamation_params() functions are used
+ * to set the dynamic variability range (or options) for the budget;
+ * <li>the frsh_feedback_set_spare() function is used to communicate to
+ * the FMGR module what is the spare virtual resource that is used
+ * to reserve a fraction of resource availability by FMGR-enabled
+ * applications, so to avoid a complete occupation of the system
+ * (this is needed in common cases if one wants to keep a good
+ * performance of the QoS control loops);
+ * such spare vres needs to have been previously negotiated through
+ * the usual functions in the FRSH Core module;
+ * <li>the frsh_feedback_set_desired_budget() function is used to
+ * dynamically fine-tune the budget request for the application,
+ * leaving to the FMGR module the freedom to fulfill the requests
+ * made by all the applications in the system according to global
+ * QoS control goals, as well as to the importance and weight
+ * parameters that may be specified by the applications for individual
+ * virtual resources.
+ * </ul>
+ *
* @{
*
**/
-
-
/**
- * frsh_feedback_reserve()
+ * frsh_feedback_set_spare()
*
- * This function reserves a portion of spare space to be distributed
- * among the vres with this method.
+ * This function is used to tell the FRSH FEEDBACKCTRL module what is
+ * the spare contract that is used as a "reserve" of computation
+ * resources that may be used by other contracts making use of adaptive
+ * reservations.
+ *
+ * @note
+ * No threads must be ever attached to the contract identified by
+ * spare_id. If this happens, behaviour is unspecified.
+ *
+ * @note
+ * This function must be called only once. If it is called more than
+ * once, then the behaviour is unspecified.
**/
-int frsh_feedback_reserve(frsh_spare_subset_t utilization);
+int frsh_feedback_set_spare(const frsh_contract_t *spare_contract);
+/**
+ * frsh_feedback_get_spare()
+ *
+ * Get version of the frsh_feedback_set_spare() function.
+ **/
+int frsh_feedback_get_spare(frsh_contract_t *spare_contract);
+/**
+ * frsh_feedback_set_desired_budget()
+ *
+ * This function sets the budget request that would best suite the
+ * needs of the application for the very next server periods. The
+ * budget actually used for the vres instances (application jobs),
+ * that may be retrieved through a frsh_feedback_get_actual_budget() call,
+ * is dynamically changed by the FMGR Module, and may be less than
+ * the required value, as due to the following rules:
+ *
+ * <ul>
+ * <li>if the required budget is less than the minimum guaranteed
+ * negotiated for the vres, then it is always granted;
+ * <li>if the set of requested budgets is schedulable, then all the
+ * requests are granted, except for what stated in the note below;
+ * <li>if the set of requested budgets overcomes the resource capacity
+ * and the required budget is higher than the minimum guaranteed
+ * negotiated for the vres, then the FMGR module makes an attempt to
+ * fulfill the application request by using also the spare computation
+ * resources that have been reserved through the
+ * frsh_feedback_set_spare() call.
+ * </ul>
+ *
+ * Before any frsh_feedback_set_desired_budget() call, the desired budget
+ * is assumed to be equal to the maximum budget value set during contract
+ * negotiation.
+ *
+ * @note
+ * If the requested budget is higher than the maximum value negotiated
+ * for the vres, then an error is returned.
+ *
+ * @note
+ * The actual budget that is used for a vres may change dynamically
+ * and asynchronously with respect to the threads attached to the vres,
+ * due to other contracts being negotiated, renegotiated or terminated,
+ * or due the call of the frsh_feedback_set_desired_budget() function
+ * for other virtual resources.
+ *
+ * @param[in] p_budget_in
+ * The new budget to set as desired.
+ **/
+int frsh_feedback_set_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_in);
/**
- * frsh_vres_set_next_budget()
+ * frsh_feedback_get_desired_budget()
*
- * This function reserves a portion of spare space to be distributed
- * among the vres with this method.
+ * Get version of the frsh_feedback_set_desired_budget() function.
+ *
+ * @param[out] p_budget_out
+ * The last budget set as desired through a frsh_feedback_set_desired_budget()
+ * call, or the maximum budget set during contract negotiation, if no such
+ * call ever occurred.
**/
-int frsh_vres_set_next_budget(frsh_vres_id_t vres_id, struct timespec new_budget);
+int frsh_feedback_get_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_out);
+/**
+ * frsh_feedback_get_actual_budget()
+ *
+ * Retrieve the actual budget that is being dynamically used by the FMGR module for
+ * the specified vres. The value returned by this function (in the budget parameter)
+ * for a given vres may change dynamically as a result of a call to the
+ * frsh_feedback_set_desired_budget() function for the same or other virtual resources.
+ **/
+int frsh_feedback_get_actual_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *budget);
/*@}*/
+
+FRSH_CPP_END_DECLS
+
#endif
projects / frescor / frsh-include.git / blobdiff