frsh_feedback_control.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2009 FRESCOR consortium partners:
   3 //
   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
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org for a link to partners' websites
  17 //
  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
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 //   FSF API web pages: http://marte.unican.es/fsf/docs
  32 //                      http://shark.sssup.it/contrib/first/docs/
  33 //
  34 //   This file is part of FRSH (FRescor ScHeduler)
  35 //
  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.
  46 //
  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
  56
  57 //==============================================
  58 //  ******** *******    ********  **      **
  59 //  **///// /**////**  **//////  /**     /**
  60 //  **      /**   /** /**        /**     /**
  61 //  ******* /*******  /********* /**********
  62 //  **////  /**///**  ////////** /**//////**
  63 //  **      /**  //**        /** /**     /**
  64 //  **      /**   //** ********  /**     /**
  65 //  //       //     // ////////   //      //
  66 //
  67 // FRSH(FRescor ScHeduler), pronounced "fresh"
  68 //==============================================
  69
  70 #ifndef _FRSH_FEEDBACK_CONTROL_H_
  71 #define _FRSH_FEEDBACK_CONTROL_H_
  72
  73 #include <time.h>
  74
  75 //#include "frsh_feedback_control_types.h"
  76 #include "frsh_core_types.h"
  77
  78 FRSH_CPP_BEGIN_DECLS
  79
  80 #define FRSH_FEEDBACKCTRL_MODULE_SUPPORTED       1
  81
  82 /**
  83  * @file frsh_feedback_control.h
  84  **/
  85
  86 /**
  87  * @defgroup feedbackctrl Feedback Control Module
  88  *
  89  * This module provides a way to implement a QoS manager at the
  90  * application level.
  91  *
  92  * @note
  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:
  96  * <ul>
  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
 114  *       virtual resources.
 115  * </ul>
 116  *
 117  * @{
 118  *
 119  **/
 120
 121 /**
 122  * frsh_feedback_set_spare()
 123  *
 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
 127  * reservations.
 128  *
 129  * @note
 130  * No threads must be ever attached to the contract identified by
 131  * spare_id. If this happens, behaviour is unspecified.
 132  *
 133  * @note
 134  * This function must be called only once. If it is called more than
 135  * once, then the behaviour is unspecified.
 136  **/
 137 int frsh_feedback_set_spare(const frsh_contract_t *spare_contract);
 138
 139 /**
 140  * frsh_feedback_get_spare()
 141  *
 142  * Get version of the frsh_feedback_set_spare() function.
 143  **/
 144 int frsh_feedback_get_spare(frsh_contract_t *spare_contract);
 145
 146 /**
 147  * frsh_feedback_set_desired_budget()
 148  *
 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:
 155  *
 156  * <ul>
 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.
 167  * </ul>
 168  *
 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
 171  * negotiation.
 172  *
 173  * @note
 174  * If the requested budget is higher than the maximum value negotiated
 175  * for the vres, then an error is returned.
 176  *
 177  * @note
 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.
 183  *
 184  * @param[in] p_budget_in
 185  * The new budget to set as desired.
 186  **/
 187 int frsh_feedback_set_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_in);
 188
 189 /**
 190  * frsh_feedback_get_desired_budget()
 191  *
 192  * Get version of the frsh_feedback_set_desired_budget() function.
 193  *
 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.
 198  **/
 199 int frsh_feedback_get_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_out);
 200
 201 /**
 202  * frsh_feedback_get_actual_budget()
 203  *
 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.
 208  **/
 209 int frsh_feedback_get_actual_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *budget);
 210
 211 /*@}*/
 212
 213
 214 FRSH_CPP_END_DECLS
 215
 216 #endif