Spare capacity sharing module

Functions
int	fsf_set_contract_reclamation_parameters (fsf_contract_parameters_t *contract, const struct timespec *budget_max, const struct timespec *period_min, fsf_granularity_t granularity, const fsf_utilization_set_t *utilization_set, int quality, int importance)
int	fsf_get_contract_reclamation_parameters (const fsf_contract_parameters_t *contract, struct timespec *budget_max, struct timespec *period_min, fsf_granularity_t *granularity, fsf_utilization_set_t *utilization_set, int *quality, int *importance)
int	fsf_request_change_quality_and_importance (fsf_server_id_t server, int new_importance, int new_quality)
int	fsf_get_total_quality (fsf_server_id_t server, int *total_quality)
int	fsf_get_available_capacity (fsf_server_id_t server, uint32_t *capacity)

---

Detailed Description

Many applications have requirements for flexibility regarding the amount of resources that can be used. The spare capacity module allows the system to share the spare capacity that may be left over from the negotiation of the service contracts, in a static way. During the negotiation, the minimum requested resources are granted to each server, if possible. Then, if there is any extra capacity left, it is distributed among those applications that have expressed their ability to take advantage of it.

This module include functions for sharing the spare capacity in the system between the servers. It allows to mainly to specify additional contract parameters to allow the sharing of the spare capacity.

The features provided by this module are different from the services provided by the Dynamic reclamation module. This module influences the negotiation procedure (see the Negotiate contract functions module).

---

Function Documentation

int fsf_get_available_capacity (  fsf_server_id_t  server, uint32_t *  capacity )

This operation stores in the variable pointed to by capacity the spare capacity currently available for the importance level of the specified server. The capacity is the utilization (of the processor or of the network) and it is represented by an integer number between 0 (no utilization) and UINT32_MAX (all utilization). Return values: FSF_ERR_BAD_ARGUMENT  if the value of the server argument is not in range or capacity is NULL FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  if the calling thread is not scheduled under the FSF FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not running FSF_ERR_NOT_CONTRACTED_SERVER  if the server has been cancelled or it is not valid

int fsf_get_contract_reclamation_parameters (  const fsf_contract_parameters_t *  contract, struct timespec *  budget_max, struct timespec *  period_min, fsf_granularity_t *  granularity, fsf_utilization_set_t *  utilization_set, int *  quality, int *  importance )

The operation obtains from the specified contract parameters object its granularity, utilization set, quality, and importance. Then copies them to the variables pointed to by the specified input parameters. Only the utilization_values of the utilization_set that are in use, are copied (according to its size field). Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  : if contract is NULL See also: fsf_set_contract_reclamation_parameters

int fsf_get_total_quality (  fsf_server_id_t  server, int *  total_quality )

This operation calculates the sum of the quality parameters for all servers in the system of importance level equal to that of the specified server, and stores it in the variable pointed to by total_quality. Parameters: [in]  server server id [out]  total_quality the total quality in the system Return values: FSF_ERR_BAD_ARGUMENT  if the value of the server argument is not in range or total_quality is NULL FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  if the calling thread is not scheduled under the FSF FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not running FSF_ERR_NOT_CONTRACTED_SERVER  if the server has been cancelled or it is not valid

int fsf_request_change_quality_and_importance (  fsf_server_id_t  server, int  new_importance, int  new_quality )

The operation enqueues a request to change the quality and importance parameters of the specified server, and returns immediately. The change operation is performed as soon as it is practical; meanwhile the system operation will continue normally. Parameters: server  server id new_importance  the new importance new_quality  the new requested quality Return values: FSF_ERR_BAD_ARGUMENT  if the value of the server argument is not in range or (quality < 0) (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS). FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  if the calling thread is not scheduled under the FSF FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not running FSF_ERR_NOT_CONTRACTED_SERVER  if the server has been cancelled or it is not valid

int fsf_set_contract_reclamation_parameters (  fsf_contract_parameters_t *  contract, const struct timespec *  budget_max, const struct timespec *  period_min, fsf_granularity_t  granularity, const fsf_utilization_set_t *  utilization_set, int  quality, int  importance )

The operation updates the specified contract parameters object by setting its maximum usable budget, minimum period, granularity, utilization set, quality, and importance to the specified input parameters. Parameters: [in]  contract pointer ot the contract [in]  budget_max maximum budget this contract can obtain [in]  period_min minimum period this contract can obtain [in]  granularity can be either FSF_CONTINUOUS or FSF_DISCRETE [in]  utilization_set in case the granularity is set to FSF_DISCRETE it contains a list possible pairs (budget,period) [in]  quality a number between FSF_MIN_QUALITY and FSF_MAX_QUALITY, to control how the spare capacity is shared between contracts with the same importance. The higher is this number, the more likely we get a large increase in the capacity [in]  importance a numer between FSF_MIN_IMPORTANCE and FSF_MAX_IMPORTANCE, used to control how the spare capacity is shared. The higher the number, the more likely we get some spare capacity. Return values: 0  if the call is succesful FSF_ERR_BAD_ARGUMENT  if contract is NULL or one of the following conditions is true: (budget_max value is grater than period_max or smaller than budget_min); (period_min is smaller than budget_mint or larger than period_max); (granularity is neither FSF_CONTINUOUS nor FSF_DISCRETE); (granularity is FSF_CONTINUOUS and utilization_set is not FSF_NULL_UTILIZATION_SET) (granularity is FSF_DISCRETE and utilization_set is FSF_NULL_UTILIZATION_SET) (utilization_set is not FSF_NULL_UTILIZATION_SET and (size of utilization_set less than 2 or greater than FSF_MAX_N_UTILIZATION_VALUES) (quality < 0) (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS) (the utilization_set elements are not in increasing utilization order) (the first utilization value in the utilization_set does not match the pair (budget_min, period_max) of the contract); (the last utilization value in the utilization_set does not match the pair (budget_max, period_min) of the contract).

---