1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2009 FRESCOR consortium partners:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politécnica Valencia, SPAIN
9 // Czech Technical University in Prague, CZECH REPUBLIC
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org for a link to partners' websites
18 // FRESCOR project (FP6/2005/IST/5-034026) is funded
19 // in part by the European Union Sixth Framework Programme
20 // The European Union is not liable of any use that may be
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // FSF API web pages: http://marte.unican.es/fsf/docs
32 // http://shark.sssup.it/contrib/first/docs/
34 // This file is part of FRSH (FRescor ScHeduler)
36 // FRSH is free software; you can redistribute it and/or modify it
37 // under terms of the GNU General Public License as published by the
38 // Free Software Foundation; either version 2, or (at your option) any
39 // later version. FRSH is distributed in the hope that it will be
40 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
41 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
42 // General Public License for more details. You should have received a
43 // copy of the GNU General Public License along with FRSH; see file
44 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
45 // Cambridge, MA 02139, USA.
47 // As a special exception, including FRSH header files in a file,
48 // instantiating FRSH generics or templates, or linking other files
49 // with FRSH objects to produce an executable application, does not
50 // by itself cause the resulting executable application to be covered
51 // by the GNU General Public License. This exception does not
52 // however invalidate any other reasons why the executable file might be
53 // covered by the GNU Public License.
54 // -----------------------------------------------------------------------
55 //frsh_feedback_control.h
57 //==============================================
58 // ******** ******* ******** ** **
59 // **///// /**////** **////// /** /**
60 // ** /** /** /** /** /**
61 // ******* /******* /********* /**********
62 // **//// /**///** ////////** /**//////**
63 // ** /** //** /** /** /**
64 // ** /** //** ******** /** /**
65 // // // // //////// // //
67 // FRSH(FRescor ScHeduler), pronounced "fresh"
68 //==============================================
70 #ifndef _FRSH_FEEDBACK_CONTROL_H_
71 #define _FRSH_FEEDBACK_CONTROL_H_
75 //#include "frsh_feedback_control_types.h"
76 #include "frsh_core_types.h"
80 #define FRSH_FEEDBACKCTRL_MODULE_SUPPORTED 1
83 * @file frsh_feedback_control.h
87 * @defgroup feedbackctrl Feedback Control Module
89 * This module provides a way to implement a QoS manager at the
93 * Please, note that, in order to exploit the feedback-scheduling
94 * functionality of FRESCOR, an application needs to use a set of
95 * different functions:
97 * <li>the frsh_contract_set_basic_params() and the
98 * frsh_contract_set_reclamation_params() functions are used
99 * to set the dynamic variability range (or options) for the budget;
100 * <li>the frsh_feedback_set_spare() function is used to communicate to
101 * the FMGR module what is the spare virtual resource that is used
102 * to reserve a fraction of resource availability by FMGR-enabled
103 * applications, so to avoid a complete occupation of the system
104 * (this is needed in common cases if one wants to keep a good
105 * performance of the QoS control loops);
106 * such spare vres needs to have been previously negotiated through
107 * the usual functions in the FRSH Core module;
108 * <li>the frsh_feedback_set_desired_budget() function is used to
109 * dynamically fine-tune the budget request for the application,
110 * leaving to the FMGR module the freedom to fulfill the requests
111 * made by all the applications in the system according to global
112 * QoS control goals, as well as to the importance and weight
113 * parameters that may be specified by the applications for individual
122 * frsh_feedback_set_spare()
124 * This function is used to tell the FRSH FEEDBACKCTRL module what is
125 * the spare contract that is used as a "reserve" of computation
126 * resources that may be used by other contracts making use of adaptive
130 * No threads must be ever attached to the contract identified by
131 * spare_id. If this happens, behaviour is unspecified.
134 * This function must be called only once. If it is called more than
135 * once, then the behaviour is unspecified.
137 int frsh_feedback_set_spare(const frsh_contract_t *spare_contract);
140 * frsh_feedback_get_spare()
142 * Get version of the frsh_feedback_set_spare() function.
144 int frsh_feedback_get_spare(frsh_contract_t *spare_contract);
147 * frsh_feedback_set_desired_budget()
149 * This function sets the budget request that would best suite the
150 * needs of the application for the very next server periods. The
151 * budget actually used for the vres instances (application jobs),
152 * that may be retrieved through a frsh_feedback_get_actual_budget() call,
153 * is dynamically changed by the FMGR Module, and may be less than
154 * the required value, as due to the following rules:
157 * <li>if the required budget is less than the minimum guaranteed
158 * negotiated for the vres, then it is always granted;
159 * <li>if the set of requested budgets is schedulable, then all the
160 * requests are granted, except for what stated in the note below;
161 * <li>if the set of requested budgets overcomes the resource capacity
162 * and the required budget is higher than the minimum guaranteed
163 * negotiated for the vres, then the FMGR module makes an attempt to
164 * fulfill the application request by using also the spare computation
165 * resources that have been reserved through the
166 * frsh_feedback_set_spare() call.
169 * Before any frsh_feedback_set_desired_budget() call, the desired budget
170 * is assumed to be equal to the maximum budget value set during contract
174 * If the requested budget is higher than the maximum value negotiated
175 * for the vres, then an error is returned.
178 * The actual budget that is used for a vres may change dynamically
179 * and asynchronously with respect to the threads attached to the vres,
180 * due to other contracts being negotiated, renegotiated or terminated,
181 * or due the call of the frsh_feedback_set_desired_budget() function
182 * for other virtual resources.
184 * @param[in] p_budget_in
185 * The new budget to set as desired.
187 int frsh_feedback_set_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_in);
190 * frsh_feedback_get_desired_budget()
192 * Get version of the frsh_feedback_set_desired_budget() function.
194 * @param[out] p_budget_out
195 * The last budget set as desired through a frsh_feedback_set_desired_budget()
196 * call, or the maximum budget set during contract negotiation, if no such
197 * call ever occurred.
199 int frsh_feedback_get_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_out);
202 * frsh_feedback_get_actual_budget()
204 * Retrieve the actual budget that is being dynamically used by the FMGR module for
205 * the specified vres. The value returned by this function (in the budget parameter)
206 * for a given vres may change dynamically as a result of a call to the
207 * frsh_feedback_set_desired_budget() function for the same or other virtual resources.
209 int frsh_feedback_get_actual_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *budget);