From: sangorrin Date: Thu, 6 Nov 2008 16:24:29 +0000 (+0000) Subject: change of the group negotiation API X-Git-Url: https://rtime.felk.cvut.cz/gitweb/frescor/frsh-include.git/commitdiff_plain/536647f5e8057d973cb68cb1012fc319bce55180 change of the group negotiation API git-svn-id: http://www.frescor.org/private/svn/frescor/frsh/trunk/include@1375 35b4ef3e-fd22-0410-ab77-dab3279adceb --- diff --git a/frsh_core.h b/frsh_core.h index 1507372..9f323d5 100644 --- a/frsh_core.h +++ b/frsh_core.h @@ -670,13 +670,13 @@ int frsh_timed_wait /** * frsh_vresperiod_wait() - * + * * Suspend the calling thread until the start of the specified virtual * resource period, for a synchronized workload. - * + * * Virtual resource periods are numbered. The number of the current * period can be obtained through the frsh_vres_get_period_number() - * operation. + * operation. **/ int frsh_vresperiod_wait (const frsh_vres_id_t vres, @@ -685,7 +685,7 @@ int frsh_vresperiod_wait /** * frsh_vres_get_period() - * + * * Return the current period number, for a virtual resource of * synchronized workload. **/ @@ -1164,71 +1164,19 @@ int frsh_vres_get_renegotiation_status * @{ **/ -/** - * frsh_group_negotiate() - * - * This function negotiates atomically a group of new contracts - * while giving the possibility of cancellling others. - * - * If the on-line admission test is enabled, FRSH analizes the - * schedulability of the context that results in the new contract - * situation with removed and added contracts. - * - * If the overall negotiation is successful, all actions will be taken - * inmediatly: the creation of new vres for the contract_up list - * and the cancellation of the designated ones. - * - * If for any reason one of the contracts is not accepted, a - * corresponding error will be returned and no actions will be taken, - * the previous context will be preserved. - * - * This call is a synchronous, potentially blocking operation. It - * returns when the system has rejected the contracts or accepted them - * and made them effective. - * - * @param[in] contracts_up List of new proposed contracts - * - * @param[in] vres_down List of vres_id to be canceled - * - * @param[out] vres_up vres_id assigned by the system to the - * corresponding contracts_up. - * - * @return 0 if no error \n - * . - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not - * running \n - * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH - * main scheduler \n - * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled - * under FRSH \n - * FRSH_ERR_BAD_ARGUMENT : if any of the vres_up or accepted arguments - * is NULL, if the contracts_up and vres_down arguments are both NULL, - * or any of them has erroneous size or its elements are NULL or not in the - * valid range respectively - **/ -int frsh_group_negotiate - (const frsh_contracts_group_t *contracts_up, - const frsh_vres_group_t *vres_down, - frsh_vres_group_t *vres_up); - - - /** * frsh_group_change_mode_sync() * - * An extension of frsh_group_negotiate() by adding the possibility of - * specifying also group contract renegotiation and removal. - * - * NOTE: This function will be implemented in a second phase after - * having fully implemented frsh_group_negotiate() in order to - * better grasp possible issues that the problems it may raise. + * This function performs a set of negotiation operations which can + * include: adding new contracts (neg), modifying existing vres (reneg) + * or cancelling existing vres (cancel). * - * This is a draft of the specification, it is yet subject to - * change. + * If one of the group operations has a NULL value, unless it causes an + * inconsistency the system will suppose that no operation of that + * type (neg, reneg or cancel) should be done. * - * This operation performs a global (re)negotiation of a group of - * contracts in an atomic way. Contracts can be added, canceled or - * renegotiated. Note that any of the groups can be empty. + * The virtual resources resulting from negotiations of new contracts are + * returned in the parameter 'new_vres' which must be provided by the user. * * If the on-line admission test is enabled, FRSH analizes the * schedulability of the context that would result in the new @@ -1239,116 +1187,131 @@ int frsh_group_negotiate * update of vres) have been carried out to reach the new running * context. * - * If for any reason one of the contracts is not accepted a - * corresponding error shall be returned and no changes will be made - * to the previously running context. + * If any of the contracts is not accepted a corresponding error shall be + * returned and no changes will be made to the previously running context. * * This call is a synchronous, potentially blocking operation. It - * returns when the system has rejected the contracts or accepted them - * and made them effective. There is also an asynchronous - * (non-blocking) version of this function below. - * - * @param[in] contracts_new_vres Contracts to be added. - * @param[out] vres_id_new vres_id's corresponding to the new - * contracts. - * @param[in] contracts_update_vres New contracts for vres to - * be updated. - * @param[in] vres_update vres_id's corresponding to the - * contracts that have to be updated. - * @param[in] vres_removed Vres_id's to be removed. + * returns when the system has rejected the contracts or accepted + * and made them effective. + * + * @param[in] contracts_to_neg List of new contracts to negotiate + * @param[in] contracts_to_reneg List of contracts to renegotiate + * @param[in] vres_to_reneg List of vres to renegotiate + * @param[in] vres_to_cancel List of vres to cancel + * @param[out] new_vres List of vres of new contracts. * * @return 0 if no error \n - * FRSH_ERR_BAD_ARGUMENT Invalid pointer or vres_id ranges. \n + * FRSH_ERR_BAD_ARGUMENT Invalid pointer or group identifier. \n * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n - * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided - * vres_ids is not recognised. \n + * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids + * is not recognised. \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread - * is not scheduled under FRSH. \n - * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong - * or not running. \n + * is not scheduled under FRSH. \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or + * not running. \n * FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of - * FRSH main scheduler. \n + * FRSH main scheduler. \n * FRSH_ERR_REJECTED_CONTRACT: The negotiation of one of the - * proposed contracts has failed. - * + * proposed contracts has failed. **/ int frsh_group_change_mode_sync - (const frsh_contracts_group_t *contracts_new_vres, - frsh_vres_group_t *vres_id_new, - const frsh_contracts_group_t *contracts_update_vres, - const frsh_vres_group_t *vres_update, - const frsh_vres_group_t *vres_removed); - + (const frsh_contracts_group_t *contracts_to_neg, + const frsh_contracts_group_t *contracts_to_reneg, + const frsh_vres_group_t *vres_to_reneg, + const frsh_vres_group_t *vres_to_cancel, + frsh_vres_group_t *new_vres); /** * frsh_group_change_mode_async() * - * This operation enqueues a global renegotiation of a group of - * contracts (with a possible addition of new vres) and returns - * immediately. The renegotiation is performed asynchronously as soon - * as it is practical. - * - * NOTE: This function will be implemented in a second phase after - * having fully implemented frsh_group_negotiate() in order to - * better grasp possible issues that the problem may raise. - * - * This is a draft of the specification, it is yet subject to - * change. - * - * This is an asynchronous (non-blocking) version of - * frsh_group_change_mode_sync(). Note however that there must - * be at least one existing thread involved in the operation (to be - * canceled or have its contract updated). An operation of puring - * adding a group of new contracts can only be done synchronously. - * - * The status of the operation (in progress, admitted or rejected) can - * be queried via frsh_vres_get_renegotiation_status() invoked for any of - * the vres involved in the renegotiation (updated or to be - * removed). As an option, a signal can be sent to the caller to - * notify the end-result of the operation. - * - * @param[in] contracts_new_vres Contracts for new vres to be - * added. - * @param[in] contract_labels Contract labels for the corresponding new - * vres to be added. - * @param[out] vres_id_new vres_id's corresponding to the new - * contracts. - * @param[in] contracts_update_vres New contracts for vres to - * be updated. - * @param[in] vres_update vres_id's corresponding to the - * contracts that have to be updated. - * @param[in] vres_removed vres_id's to be removed. - * - * @param[in] sig_notify Signal number where the coller expects to - * receive the information. - * @param[in] sig_value Signal data associated with that signal. + * This is an asynchronous (non-blocking) version of the previous function, + * frsh_group_change_mode_sync() and thus, it returns inmediately. + * + * The status of the change of mode and the identifiers for new virtual + * resources must be requested with the function 'frsh_group_get_status' + * by using the return parameter 'group'. + * + * As in the asynchronous renegotiations, when the operation is completed, + * the user is notified with a signal so he can check the final result with + * 'frsh_group_get_status'. In case that FRSH_NULL_SIGNAL is used, no + * signal will be sent to the user. + * + * @param[in] contracts_to_neg List of new contracts to negotiate + * @param[in] contracts_to_reneg List of contracts to renegotiate + * @param[in] vres_to_reneg List of vres to renegotiate + * @param[in] vres_to_cancel List of vres to cancel + * @param[in] signal Signal number to notify completion of + * the change of mode. If FRSH_NULL_SIGNAL, + * no signal will be raised. + * @param[in] signal_info Data associated to the signal + * @param[out] group The group identifier to get the status * * @return 0 if no error \n - * FRSH_ERR_BAD_ARGUMENT Invalid pointer or vres_id ranges. Also - * when the request is for adding only new contracts. \n + * FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n - * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided - * vres_id's is not recognised. \n + * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids + * is not recognised. \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread - * is not scheduled under FRSH. \n - * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong - * or not running. \n + * is not scheduled under FRSH. \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or + * not running. \n * FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of - * FRSH main scheduler. \n - * FRSH_ERR_REJECTED_CONTRACT: The negotiation of one of the - * proposed contracts has failed. + * FRSH main scheduler. **/ int frsh_group_change_mode_async - (const frsh_contracts_group_t *contracts_new_vres, - frsh_vres_group_t *vres_id_new, - const frsh_contracts_group_t *contracts_update_vres, - const frsh_vres_group_t *vres_update, - const frsh_vres_group_t *vres_removed, - const frsh_signal_t signal_notify, - const frsh_signal_info_t signal_info); + (const frsh_contracts_group_t *contracts_to_neg, + const frsh_contracts_group_t *contracts_to_reneg, + const frsh_vres_group_t *vres_to_reneg, + const frsh_vres_group_t *vres_to_cancel, + const frsh_signal_t signal, + const frsh_signal_info_t signal_info, + frsh_group_id_t *group); + +/** + * frsh_group_get_status() + * + * This function is similar to 'frsh_vres_get_renegotiation_status' but it + * is intented for group negotiations (changes of mode). + * + * The operation reports on the status of the last negotiation + * operation enqueued for the specified group identifier. + * + * The status value can be one of the following values: + * + * - FRSH_RS_IN_PROGRESS: the change of mode is in progress + * - FRSH_RS_REJECTED: the change of mode was not accepted + * - FRSH_RS_ADMITTED: the change of mode was accepted + * - FRSH_RS_NOT_REQUESTED: no change of mode has been requested yet + * + * When status returns 'FRSH_RS_ADMITTED', the array 'new_vres' contains + * the values for the new virtual resources (if there was any). + * + * This function frees the group identifier when status returns something + * different than FRSH_RS_IN_PROGRESS so further calls to this function may + * return inconsistent values. + * + * @param[in] group The group identifier + * @param[out] status The status of the change of mode + * @param[out] new_vres List of vres for the negotiation of new contracts. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n + * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n + * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids + * is not recognised. \n + * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread + * is not scheduled under FRSH. \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or + * not running. \n + * FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of + * FRSH main scheduler. + **/ +int frsh_group_get_status(const frsh_group_id_t group, + frsh_renegotiation_status_t *status, + frsh_vres_group_t *new_vres); -/*@}*/ +/*@}*/ ////////////////////////////////////////////////////