#include "frsh_core.h"
+/**
+ * @file frsh_spare_capacity.h
+ **/
+
#define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED 1
* There are no specific negotiation calls because the algorithms used
* in the core module take already these min-max ranges into account.
*
+ * An operation is available for applications to ask for a stability
+ * period of a specified length. The framework will then return the
+ * total capacity (execution time budget and virtual resource period)
+ * that the application is guaranteed to receive in this stability
+ * period. The rationale for this service is that jobs may span a
+ * number of virtual resource periods, and need to have a guaranteed
+ * amount of capacity before they can choose a higher quality (longer
+ * execution time) method, when multiple methods are available. Also
+ * applications may require that the capacity provided to them and
+ * hence the quality of results produced remains consistent for a
+ * period of time, so that consistent behaviour is provided for the
+ * user (e.g. multimedia applications).
+ *
+ * Requesting a new stability period has the effect of cancelling any
+ * previous one. So a subsequent request for stability up to the same
+ * point in time could return a lower total capacity, if spare capacity
+ * re-allocation is in progress due to the admission of a new
+ * application. If a stability period expires without having explicitly
+ * set a new one, the system may decide to perform a reallocation of
+ * spare resources at that point, or may defer this decision to some
+ * future point in time when it is appropriate. In both cases, a new
+ * stability period will start when the new spare capacity assignment
+ * is in effect.
+ *
+ *
* NOTE: When we talk here about "spare capacity" we mean STATIC extra
* capacity at NEGOTIATION TIME. This is the minimum capacity
* that the vres will get based on contract negotiation.
* parameters.
*
* @param contract Contract object
- * @param remaining_stability_time Time in which FRSH guarantees that the
+ * @param stability_time Time in which FRSH guarantees that the
* assigned budget and period will remain permanent
* even across renegotiations.
* @param budget_max The maximum budget that the vres aspires to
* importance, spare capacity will be distributed
* proportionally to weight levels.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if contract is NULL or
- * (budget_max value is grater than period_max or smaller than budget_min) or
- * (period_min is smaller than budget_mint or larger than period_max) or
- * (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE) or
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n
+ * (budget_max value is grater than period_max or smaller than budget_min) \b or \n
+ * (period_min is smaller than budget_mint or larger than period_max) \b or \n
+ * (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE) \b or \n
* (granularity is FRSH_CONTINUOUS and
- * utilization_set is not FRSH_NULL_UTILIZATION_SET) or
+ * utilization_set is not FRSH_NULL_UTILIZATION_SET) \b or \n
* (granularity is FRSH_DISCRETE and
- * utilization_set is FRSH_NULL_UTILIZATION_SET) or
+ * utilization_set is FRSH_NULL_UTILIZATION_SET \b or \n
* (utilization_set is not FRSH_NULL_UTILIZATION_SET and
* (size of utilization_set less than 2 or greater
- * than FRSH_MAX_N_UTILIZATION_VALUES) ) or
- * (weight < 0) or
- * (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) or
- * (the utilization_set elements are not in increasing utilization order) or
+ * than FRSH_MAX_N_UTILIZATION_VALUES) ) \b or \n
+ * (weight < 0) \b or \n
+ * (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) \b or \n
+ * (the utilization_set elements are not in increasing utilization order) \b or \n
* (the first utilization value in the utilization_set does not match
- * the pair (budget_min, period_max) of the contract) or
+ * the pair (budget_min, period_max) of the contract) \b or \n
* (the last utilization value in the utilization_set does not match
* the pair (budget_max, period_min) of the contract)
*
**/
int frsh_contract_set_reclamation_params(frsh_contract_t *contract,
- const struct timespec *remaining_stability_time,
+ const struct timespec *stability_time,
const struct timespec *budget_max,
const struct timespec *period_min,
frsh_granularity_t granularity,
* that are in use, are copied (according to its size field).
*
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT : if contract is NULL
*
**/
int frsh_contract_get_reclamation_params
(const frsh_contract_t *contract,
- struct timespec *remaining_stability_time,
+ struct timespec *stability_time,
struct timespec *budget_max,
struct timespec *period_min,
frsh_granularity_t *granularity,
/**
* frsh_vres_get_remaining_stability_time()
*
- * This operation returns the remaining_stability_time for the vres.
+ * This operation returns the stability_time for the vres.
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
- * capacity is NULL
+ * capacity is NULL \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
- * scheduled under the FRSH
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
+ * scheduled under FRSH \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
* FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
- * is not valid
+ * is not valid \n
*
**/
int frsh_vres_get_remaining_stability_time(frsh_vres_id_t vres,
- struct timespec *remaining_stability_time);
+ struct timespec *stability_time);
/**
- * frsh_spare_get_capacity()
+ * frsh_resource_get_capacity()
*
* This operation gets the spare capacity currently assigned to an
* importance level. The capacity is the number obtained divided by
* UINT32_MAX, and it represents the processor or network
* utilization.
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
- * capacity is NULL
+ * capacity is NULL \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
- * scheduled under the FRSH
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
+ * scheduled under the FRSH \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
* FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
- * is not valid
+ * is not valid \n
*
**/
-int frsh_spare_get_capacity(const frsh_resource_id_t resource_id,
- const int importance,
- uint32_t *capacity);
+int frsh_resource_get_capacity(const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
+ const int importance,
+ uint32_t *capacity);
/**
- * frsh_spare_get_total_weight()
+ * frsh_resource_get_total_weight()
*
* This operation calculates the sum of the weight parameters for all
* vres in the system for a certain importance level at a specific
* resource_id.
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
* total_weight is NULL \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
* FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
* is not valid \n
**/
-int frsh_spare_get_total_weight
- (const frsh_resource_id_t resource_id,
+int frsh_resource_get_total_weight
+ (const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
const int importance,
- uint32_t *capacity);
+ uint32_t *total_weight);
/**
projects / frescor / frsh-include.git / blobdiff