// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+// Copyright (C) 2006 - 2008 FRESCOR consortium partners:
//
// Universidad de Cantabria, SPAIN
// University of York, UK
// Visual Tools S.A. SPAIN
// Rapita Systems Ltd UK
// Evidence ITALY
-//
+//
// See http://www.frescor.org for a link to partners' websites
//
// FRESCOR project (FP6/2005/IST/5-034026) is funded
//
//
// based on previous work (FSF) done in the FIRST project
-//
+//
// Copyright (C) 2005 Mälardalen University, SWEDEN
// Scuola Superiore S.Anna, ITALY
// Universidad de Cantabria, SPAIN
// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
-// This file is part of FRSH API
-//
-// FRSH API is free software; you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation; either version 2, or (at your option)
-// any later version.
+// This file is part of FRSH (FRescor ScHeduler)
//
-// FRSH API is distributed in the hope that it will be useful, but
-// WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-// General Public License for more details.
+// FRSH is free software; you can redistribute it and/or modify it
+// under terms of the GNU General Public License as published by the
+// Free Software Foundation; either version 2, or (at your option) any
+// later version. FRSH is distributed in the hope that it will be
+// useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details. You should have received a
+// copy of the GNU General Public License along with FRSH; see file
+// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
+// Cambridge, MA 02139, USA.
//
-// You should have received a copy of the GNU General Public License
-// distributed with FRSH API; see file COPYING. If not, write to the
-// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
-// 02111-1307, USA.
-//
-// As a special exception, if you include this header file into source
-// files to be compiled, this header file does not by itself cause
-// the resulting executable to be covered by the GNU General Public
-// License. This exception does not however invalidate any other
-// reasons why the executable file might be covered by the GNU General
-// Public License.
+// As a special exception, including FRSH header files in a file,
+// instantiating FRSH generics or templates, or linking other files
+// with FRSH objects to produce an executable application, does not
+// by itself cause the resulting executable application to be covered
+// by the GNU General Public License. This exception does not
+// however invalidate any other reasons why the executable file might be
+// covered by the GNU Public License.
// -----------------------------------------------------------------------
//==============================================
// **//// /**///** ////////** /**//////**
// ** /** //** /** /** /**
// ** /** //** ******** /** /**
-// // // // //////// // //
+// // // // //////// // //
//
// FRSH(FRescor ScHeduler), pronounced "fresh"
//==============================================
#include "frsh_core_types.h"
#include "frsh_spare_capacity.h"
+
+FRSH_CPP_BEGIN_DECLS
+
/**
* @defgroup core Core module
*
* We cannot call any frsh functions before frsh_init. After calling
* frsh_init, the main will be executing in the background. Then, it
* can do the negotiations and create new threads if needed. The
- * second time this function is called it fails.
+ * second time this function is called it fails.
*
* @return 0 if no error. \n
* FRSH_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already
* been called before\n
- * .
+ * .
* It may also return any of the errors that may be returned by the
* underlying operating system primitives required to perform the
* FRSH system start up
- *
+ *
**/
int frsh_init();
**/
-
/**
* frsh_contract_init()
- *
+ *
* The operation receives a pointer to a contract object
* and initializes it, setting it to the default values.
*
*
* - resource_id => 0
* - ressource_type => FRSH_CRT_PROCESSOR
- * - contract_label =>
+ * - contract_label => ""
* - budget_min => {0,0};
* - period_max => {0,0};
* - budget_max => {0,0};
* - period_min => {0,0};
- * - workload => DEFAULT_WORKLOAD => FRSH_INDETERMINATE
- * - d_equals_t => DEFAULT_D_EQUALS_T; (false or true)
+ * - workload => FRSH_WT_INDETERMINATE
+ * - d_equals_t => true
* - contract_type => FRSH_CT_REGULAR;
- * - deadline => DEFAULT_DEADLINE;
- * - budget_overrun_sig_notify => 0; (signal number)
- * - budget_overrun_sig_value => {0, NULL};
- * - deadline_miss_sig_notify => 0; (signal number)
- * - deadline_miss_sig_value => {0, NULL};
+ * - deadline => {0,0};
+ * - budget_overrun_signal => 0; (signal number)
+ * - budget_overrun_siginfo => {0, NULL};
+ * - deadline_miss_signal => 0; (signal number)
+ * - deadline_miss_siginfo => {0, NULL};
*
* - granularity => DEFAULT_GRANULARITY;
* - utilization_set; => size = 0
* - sched_policy => DEFAULT_SCHED_POLICY (FRSH_NONE)
*
* @param contract the pointer to the contract variable.
- *
+ *
* @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : contract is NULL
- *
+ *
**/
int frsh_contract_init(frsh_contract_t *contract);
-
+
/**
* frsh_contract_set_basic_params()
* bounded tasks are triggered by the scheduler (see the
* frsh_timed_wait() and frsh_synchobj_wait* operations), while
* indeterminate tasks are not; therefore, their programming model is
- * quite different).
+ * quite different).
*
* @param contract the pointer to the contract object
* @param[in] budget_min the minimum budget for the contract
* @param[in] period_max the maximum period for the contract
- * @param[in] workload the kind of workload (can be FRSH_BOUNDED,
- * FRSH_INDETERMINATE or FRSH_OVERHEAD)
+ * @param[in] workload the kind of workload (can be FRSH_WT_BOUNDED,
+ * FRSH_WT_INDETERMINATE or FRSH_OVERHEAD)
* @param[in] contract_type can be FRSH_CT_REGULAR,
* FRSH_CT_BACKGROUND, FRSH_CT_DUMMY.
- *
+ *
* @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL
- * or if only one of the timespec values is 0, and also if the
+ * or if only one of the time values is 0, and also if the
* workload or the contract type values are unknown in the
- * enumerations.
+ * enumerations.
**/
int frsh_contract_set_basic_params
(frsh_contract_t *contract,
- const struct timespec *budget_min,
- const struct timespec *period_max,
+ const frsh_rel_time_t *budget_min,
+ const frsh_rel_time_t *period_max,
const frsh_workload_t workload,
const frsh_contract_type_t contract_type);
*
* This operation obtains from the specified contract object its
* budget, period, and workload, and copies them to the places pointed
- * to by the corresponding output parameters.
+ * to by the corresponding output parameters.
*
* @param[in] contract the pointer to the contract object
* @param[out] budget_min pointer to preallocated space
* @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if one of the contract or
* pointers is NULL.
- *
+ *
**/
int frsh_contract_get_basic_params
(const frsh_contract_t *contract,
- struct timespec *budget_min,
- struct timespec *period_max,
+ frsh_rel_time_t *budget_min,
+ frsh_rel_time_t *period_max,
frsh_workload_t *workload,
frsh_contract_type_t *contract_type);
/**
* frsh_contract_set_resource_and_label()
*
- * Specify processor_id/network_id and whether it is a processor or a
- * network. Otherwise default values (type is processor and id is #0
- * will apply.
+ * Specify resource_id and type, and the contract label. Otherwise
+ * default values will apply. If the contract label is too long it is truncated
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract pointer is NULL.
**/
int frsh_contract_set_resource_and_label
(frsh_contract_t *contract,
const frsh_resource_type_t resource_type,
const frsh_resource_id_t resource_id,
- const frsh_contract_label_t contract_label);
+ const char *contract_label);
/**
* frsh_contract_get_resource_and_label()
*
- * Specify processor_id/network_id and whether it is a processor or a
- * network. Otherwise default values (processor and processor #0 will
- * apply.
+ * Obtain the resource_id and type, and the contract label.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract or the contract_label
+ * pointer is NULL.
**/
int frsh_contract_get_resource_and_label
(const frsh_contract_t *contract,
frsh_resource_type_t *resource_type,
frsh_resource_id_t *resource_id,
- frsh_contract_label_t contract_label);
+ char *contract_label);
-/**
+/**
* frsh_contract_set_timing_reqs()
*
* The operation updates the specified contract object, specifying
- * additional time-related requirements.
+ * additional time-related requirements.
*
* @param contract The pointer to the contract object
- *
- * @param [in] d_equals_t It is a boolean value, set to true (1) if
+ *
+ * @param [in] d_equals_t It is a boolean value, set to true (1) if
* we want to specify a deadline different from
- * the period for the contract.
- * @param [in] deadline If the previous parameter is set to true,
+ * the period for the contract.
+ * @param [in] deadline If the previous parameter is set to true,
* this parameter is ignored (the contract value
* will be NULL_DEADLINE internally). Otherwise, it
- * contains the desired deadline value.
- * @param [in] budget_overrun_sig_notify contains the number of the signal
- * that must be raised if the budget of the vres is overrun.
- * If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
- * be raised.
- * @param [in] budget_overrun_sig_value contains the value that will be
- * passed to the signal "catcher" when the signal is raised.
- * This parameters is not used if the budget_overrun_sig_notify
+ * contains the desired deadline value.
+ * @param [in] budget_overrun_signal contains the number of the signal
+ * that must be raised if the budget of the vres is overrun.
+ * If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
+ * be raised.
+ * @param [in] budget_overrun_siginfo contains the value that will be
+ * passed to the signal "catcher" when the signal is raised.
+ * This parameters is not used if the budget_overrun_signal
* parameter is set to FRSH_NULL_SIGNAL.
- * @param [in] deadline_miss_sig_notify contains the number of the
+ * @param [in] deadline_miss_signal contains the number of the
* signal that must be raised if the deadline of the
* vres is missed. If the value of this parameter is
- * FRSH_NULL_SIGNAL, no signal is raised.
- * @param [in] deadline_miss_sig_value contains the value that will be
+ * FRSH_NULL_SIGNAL, no signal is raised.
+ * @param [in] deadline_miss_siginfo contains the value that will be
* passed to the signal "catcher" when the signal is
- * raised. This parameter is not used if the
- * deadline_sig_notify parameter is set to NULL_SIGNAL
- *
+ * raised. This parameter is not used if the
+ * deadline_signal parameter is set to NULL_SIGNAL
+ *
* @return 0 if successful\n
* FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n
* (d_equals_t is true and deadline is not FRSH_NULL_DEADLINE) \b or \n
- * (budget_overrun_sig_notify is not a valid signal) \b or \n
- * (deadline_miss_sig_notify is not a valid signal) \b or \n
- * (d_equals_t is false but (deadline is FRSH_NULL_DEADLINE or its value
+ * (budget_overrun_signal is not a valid signal) \b or \n
+ * (deadline_miss_signal is not a valid signal) \b or \n
+ * (d_equals_t is false but (deadline is FRSH_NULL_DEADLINE or its value
* is grater than the contract's maximum period))
- *
+ *
**/
int frsh_contract_set_timing_reqs
(frsh_contract_t *contract,
const bool d_equals_t,
- const struct timespec *deadline,
+ const frsh_rel_time_t *deadline,
const frsh_signal_t budget_overrun_signal,
const frsh_signal_info_t budget_overrun_siginfo,
const frsh_signal_t deadline_miss_signal,
*
* The operation obtains the corresponding input parameters from the
* specified contract object. If d_equals_t is true, the deadline will
- * be set to FRSH_NULL_DEADLINE.
+ * be set to FRSH_NULL_DEADLINE.
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
- *
- **/
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
+ *
+ **/
int frsh_contract_get_timing_reqs
(const frsh_contract_t *contract,
bool *d_equals_t,
- struct timespec *deadline,
+ frsh_rel_time_t *deadline,
frsh_signal_t *budget_overrun_signal,
frsh_signal_info_t *budget_overrun_siginfo,
frsh_signal_t *deadline_miss_signal,
*
* Synchronisation objects provide an alternative to timers for
* bounded-workload vres to signal the end of their current job and
- * return their remaining budget to FRSH.
+ * return their remaining budget to FRSH.
*
* Instead of asking to be reactivated based on an absolute time, they
* queue themselves in a synchronisation object and will wait there
* until another vres (bounded-workload or indeterminate-workload)
* wakes them up with a signal call the earliest at the beginning of
* the next period.
- *
+ *
* Indeterminate-workload vres cannot queue themselves here because
* they don't have any budget to return. However they can signal on
* the objects to activate a waiting workload vres.
* This operation creates and initializes a synchronization object
* variable managed by the scheduler, and returns a handle to it in
* the variable pointed to by synch_handle.
- *
- * @param[out] pointer to the variable that will contain the handle to the
- * newly created synchronization object
*
- * @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0\n
- * .
- * FRSH_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization
+ * @param[out] synch_handle pointer to the variable that will contain
+ * the handle to the newly created synchronization object
+ *
+ * @return 0 if the operation is succesful
+ * FRSH_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
+ * objects in the system has already exceeded the maximum
+ *
+ * FRSH_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization
* objects in the system has already exceeded the maximum\n
* .
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
* scheduled under FRSH\n
* .
* FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- *
+ *
**/
int frsh_synchobj_create
(frsh_synchobj_handle_t *synch_handle);
* frsh_synchobj_destroy()
*
* This operation destroys the synchronization object (created by a
- * previous call to frsh_create_synch_obj) that is referenced by the
+ * previous call to frsh_synchobj_create) that is referenced by the
* synch_handle variable. After calling this operation, the
* synch_handle variable can not be used until it is initialized again
- * by a call to frsh_create_synch_obj.
+ * by a call to frsh_synchobj_create.
*
- * @param synch_handle the handle to the synchronization object
+ * @param synch_handle the handle to the synchronization object
* to be destroyed
*
* @return 0 if no error \n
*
* As a difference with frsh_timed_wait(), here the vres
* specifies to be awakened by the arrival of a signal operation
- * instead of at a precise point of time.
+ * instead of at a precise point of time.
*
* This function can also be called to schedule the first job of a
* recently created vres and make it start when a signal operation
* Except for those parameters equal to NULL pointers, the system
* reports the current period and budget for the current job, it informs
* if the deadline of the previous job was missed or not, and whether the
- * budget of the previous job was overrun or not.
+ * budget of the previous job was overrun or not.
*
* In a system with hierarchical scheduling, since this call makes the
* budget of the current period zero, the other threads in the same
* vres are not run. As mentioned above, only when the call finishes
- * the budget may be replenished.
+ * the budget may be replenished.
*
* @param synch_handle Synchronisation object upon which the vres
* will be waiting.
- * @param next_budget[out] Upon return of this function, the variable
- * pointed by this function will be equal to
- * the current vres budget. If this parameter is
+ * @param next_budget[out] Upon return of this function, the variable
+ * pointed by this function will be equal to
+ * the current vres budget. If this parameter is
* set to NULL, no action is taken
* @param next_period[out] The vres period upon return (ignored if NULL).
* @param was_deadline_missed Upon return whether the deadline was
* missed in the previous period.
- * @param was_budget_overran
+ * @param was_budget_overran
*
*
* @return 0 if success \n
* 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
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
* under FRSH \n
* FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
* vres bound to it \n
* valid or was destroyed while the vres was waiting on it. \n
* FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
* is not FRSH_BOUNDED
- *
+ *
**/
int frsh_synchobj_wait
(const frsh_synchobj_handle_t synch_handle,
- struct timespec *next_budget,
- struct timespec *next_period,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
bool *was_deadline_missed,
bool *was_budget_overran);
/**
* frsh_synchobj_wait_with_timeout()
*
-g * This call is the same as frsh_synchobj_wait() but with an extra
+ * This call is the same as frsh_synchobj_wait() but with an extra
* absolute timeout. The timed_out argument, indicates whether the
* function returned because of the expiration of the timeout 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
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
* under FRSH \n
- * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
+ * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
* vres bound to it \n
- * FRSH_ERR_BAD_ARGUMENT : if the synch_handle given is not valid or the
+ * FRSH_ERR_BAD_ARGUMENT : if the synch_handle given is not valid or the
* abs_timeout argument is NULL or its value is in the past\n
* FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
* is not FRSH_BOUNDED
- *
+ *
**/
int frsh_synchobj_wait_with_timeout
(const frsh_synchobj_handle_t synch_handle,
- const struct timespec *abs_timeout,
+ const frsh_abs_time_t *abs_timeout,
bool *timed_out,
- struct timespec *next_budget,
- struct timespec *next_period,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
bool *was_deadline_missed,
bool *was_budget_overran);
* awaken is implementation dependent. If no vres is waiting on the
* synchronization object, the notification event is queued.
*
- * @param [in] synch_handle the handle of the synchronization object to
+ * @param [in] synch_handle the handle of the synchronization object to
* notify.
*
* @return 0 if no error \n
* FRSH_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ : if the number of events stored
* in the synchronization object reaches the maximum defined in the
* configuration parameter header file
- *
+ *
* @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
**/
int frsh_synchobj_signal
* workload vres to indicate that a job has been completed (and
* that the scheduler may reassign the unused capacity of the current
* job to other vres). It is also invoked when the first job of
- * such threads has to be scheduled.
+ * such threads has to be scheduled.
*
* As an effect, the system will make the current vres's budget zero
* for the remainder of the vres's period, and will not replenish
* mentioned abobe, only when the call finishes the budget may be
* replenished.
*
- * * @param [in] abs_time absolute time at which the budget will be
+ * @param [in] abs_time absolute time at which the budget will be
* replenished
*
- * @param [out] next_budget upon return of this function, the variable
- * pointed by this function will be equal to
- * the current vres budget. If this parameter is
- * set to NULL, no action is taken.
- *
- * @param [out] next_period upon return of this function, the variable
- * pointed by this function will be equal to
- * the current vres period. If this parameter is
+ * @param [out] next_budget upon return of this function, the variable
+ * pointed by this function will be equal to
+ * the current vres budget. If this parameter is
+ * set to NULL, no action is taken.
+ *
+ * @param [out] next_period upon return of this function, the variable
+ * pointed by this function will be equal to
+ * the current vres period. If this parameter is
* set to NULL, no action is taken.
*
* @param [out] was_deadline_missed upon return of this function, the
* variable pointed by this function will be
- * equal to true if the previous vres deadline
+ * equal to true if the previous vres deadline
* was missed, to false otherwise. If this
* parameter is set to NULL, no action is
* taken.
* main scheduler \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling
* thread is not scheduled under FRSH \n
- * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
+ * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
* vres bound to it \n
* FRSH_ERR_BAD_ARGUMENT : if abs_time is NULL \n
* FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
* is not FRSH_BOUNDED
- *
+ *
*
* @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
**/
int frsh_timed_wait
- (const struct timespec *abs_time,
- struct timespec *next_budget,
- struct timespec *next_period,
+ (const frsh_abs_time_t *abs_time,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
bool *was_deadline_missed,
bool *was_budget_overran);
+
+/**
+ * frsh_vresperiod_wait()
+ *
+ * Suspend the calling thread until the start of the specified virtual
+ * resource period of a vres_id, 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.
+ **/
+int frsh_vresperiod_wait(unsigned long period_num,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
+
+
+/**
+ * frsh_vres_get_period()
+ *
+ * Return the current period number, for a virtual resource of
+ * synchronized workload.
+ **/
+int frsh_vres_get_period_number
+ (const frsh_vres_id_t vres,
+ long *period_num);
+
+
+
+
/*@}*/
///////////////////////////////////////////////////////////////////
* The following functions are used to negotiate contracts and thus
* creating vres which are the execution image of a contract.
* Besides, these functions allow to assign and unassign threads to
- * vres.
+ * vres.
*
* In the case of more than one thread per vres please refer to the
* hierarchical module.
* contract can be admitted or not based on the current contracts
* established in the system. Then it creates the vres and
* recalculates all necessary parameters for the contracts already
- * present in the system.
+ * present in the system.
*
* This is a potentially blocking operation, it returns when the
* system has either rejected the contract, or admitted it and made it
* effective. No thread is bound to the newly created vres, which
* will be idle until a thread is bound to it via frsh_thread_bind()
- * or frsh_thread_create_and_bind().
+ * or frsh_thread_create_and_bind().
*
* This operation can only be executed by threads that are already
* bound to an active vres and therefore are being scheduled by the
* 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
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
* under FRSH scheduler \n
* FRSH_ERR_BAD_ARGUMENT : if the contract or vres arguments are NULL \n
* FRSH_ERR_TOO_MANY_VRES : if there is no space for more vres
* (the maximum number of them is already reached) \n
* FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS : contract_label is not unique.
- *
+ *
**/
int frsh_contract_negotiate
(const frsh_contract_t *contract,
* The frsh_thread_attr_t parameter is overwritten as necessary to
* introduce the adequate scheduling policy and priority, according
* to the preemption level given in the contract and the
- * frsh_priority_map() function defined by the user.
- *
+ * frsh_priority_map() function defined by the user.
+ *
* @param[in] vres_id vres with which the thread will be bound.
* @param[out] thread frsh_thread_id returned by the system.
* @param attr pthread_attr taken and maybe corrected
* that will constitute the main of the
* thread.
* @param[in] arg Argument for data to be passed at the
- * thread. Set to NUL if you don't want
- * to do anything like this.
+ * thread. Set to NUL if you don't want
+ * to do anything like this.
*
* @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT : if the contract or vres arguments are
* .
* It may also return all the errors that may be returned by the
* fosa_thread_create() function call
- *
+ *
**/
int frsh_thread_create_and_bind
(const frsh_vres_id_t vres,
int frsh_thread_create_in_background
(frsh_thread_code_t thread_code,
const void *thread_arg,
- const frsh_contract_label_t contract_label,
+ const char *contract_label,
frsh_thread_attr_t *attr,
frsh_thread_id_t *thread_id,
frsh_vres_id_t *vres_id);
+
+/**
+ * frsh_thread_join_in_background()
+ *
+ * This function is aimed for external threads to join FRSH in the
+ * least disturbing possible mode.
+ *
+ * Upon calling this function by a thread which has been created
+ * natively in the OS, it joins the framework and gets inmediately
+ * bound to an on-the-fly generated background contract.
+ *
+ * In order to gain a higher priority then it can renegotiate a
+ * contract for its vres with the needed parameters.
+ *
+ * @param[in] resource_id: Resource (CPU) in which the vres will
+ * be associated.
+ *
+ * @param[in] resource_type: Resource type (should be CPU) for the
+ * contract.
+ *
+ * @param[in] label: Label to be added to the contract.
+ *
+ * @param[out] vres_id: Resulting vres_id from the on-the-fly
+ * generated background contract.
+ *
+ * @return 0 if successful\n
+ * FRSH_ERR_NOT_CONTRACTED_VRES if the thread is already
+ * bound to a vres.
+ **/
+int frsh_thread_join_in_background(frsh_resource_id_t resource_id,
+ frsh_resource_type_t resource_type,
+ const char *label,
+ frsh_vres_id_t *vres_id);
+
+
+
/**
* frsh_thread_bind()
*
* it starts consuming the vres's budget and is executed according
* to the contract established for that vres. If the thread is
* already bound to another vres, it is effectively unbound from it
- * and bound to the specified one.
+ * and bound to the specified one.
*
* It fails if the vres's policy is different than FRSH_NONE, or if
* there is already a thread bound to this vres. In order to bind
* of the vres is FRSH_OVERHEAD \n
* FRSH_ERR_ALREADY_BOUND : if the given vres has a thread already
* bound
- *
+ *
**/
int frsh_thread_bind
(const frsh_vres_id_t vres,
* FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
* main scheduler \n
* FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist \n
- * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
+ * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
* under FRSH \n
* FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
* an application defined scheduler different than the frsh
* scheduler \n
- * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
- * vres bound to it
+ * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
+ * vres bound to it
**/
int frsh_thread_unbind(const frsh_thread_id_t thread);
* of the scheduling framework, or is not bound.
*
* @return 0 if no error \n
- * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
+ * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
* under FRSH \n
- * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
+ * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
* vres bound to it \n
* FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist or the
* vres argument is NULL
- *
+ *
**/
int frsh_thread_get_vres_id(const frsh_thread_id_t thread,
frsh_vres_id_t *vres_id);
+/**
+ * frsh_vres_get_priority()
+ *
+ * This operation stores the priority currently associated
+ * with the specified vres in the variable pointed to by
+ * priority. It returns an error if the vres_id is not recognised.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
+ * of the vres argument is not in range \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+int frsh_vres_get_priority
+ (frsh_vres_id_t vres_id,
+ int *priority);
+
/**
* frsh_vres_get_contract()
*
* contract. It returns an error if the vres_id is not recognised.
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
+ * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
* of the vres argument is not in range \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
* 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 of the calling thread
- * has been cancelled or it is not valid
- *
+ * FRSH_ERR_NOT_CONTRACTED_VRES: if the vres of the calling thread
+ * has been cancelled or it is not valid
+ *
**/
int frsh_vres_get_contract
(const frsh_vres_id_t vres,
*
* This operation retrieves the vres_id whose contract_label
* corresponds to the parameter in the resource_id and resource_type
- * specified.
+ * specified.
*
* The contract label must refer to a contract negotiated
* in the same processing node in which the call is being
* scheduled under FRSH \n
* FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
* running \n
- * FRSH_ERR_CONTRACT_LABEL_UNKNOWN: if the contract_label is not known
+ * FRSH_ERR_CONTRACT_LABEL_UNKNOWN: if the contract_label is not known
**/
int frsh_resource_get_vres_from_label
- (const frsh_contract_label_t contract_label,
+ (const char *contract_label,
const frsh_resource_type_t resource_type,
const frsh_resource_id_t resource_id,
frsh_vres_id_t *vres);
* 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 of the calling thread
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
* has been cancelled or it is not valid
- *
+ *
**/
int frsh_contract_cancel (const frsh_vres_id_t vres);
* effective.
*
* @return 0 if successful \n
- * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL or the
+ * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL or the
* value of the vres argument is not in range \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
* 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 of the calling thread
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
* has been cancelled or it is not valid \n
* FRSH_ERR_REJECTED_CONTRACT : if the renegotiation fails
- *
+ *
**/
int frsh_contract_renegotiate_sync
(const frsh_contract_t *new_contract,
* contracts established in the system. If it cannot be admitted, the
* old contract remains in effect. If it can be admitted, it
* recalculates all necessary parameters for the contracts already
- * present in the system.
+ * present in the system.
*
* When the operation is completed, notification is made to the
* caller, if requested, via a signal. The status of the operation (in
* FRSH_NULL_SIGNAL, no signal will be raised.
* @param[in] signal_info: Associated info that will come with the
* signal. This parameter will be ignored
- * if signal_to_notify == FRSH_NULL_SIGNAL.
+ * if signal_to_notify == FRSH_NULL_SIGNAL.
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL, the
- * value of the vres argument is not in range or sig_notify is
+ * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL, the
+ * value of the vres argument is not in range or sig_notify is
* neither NULL nor a valid POSIX signal \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
* 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 of the calling thread
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
* has been cancelled or it is not valid
- *
+ *
**/
int frsh_contract_renegotiate_async
(const frsh_contract_t *new_contract,
* The operation reports on the status of the last renegotiation
* operation enqueued for the specified vres. It is callable even
* after notification of the completion of such operation, if
- * requested.
+ * requested.
*
* If the vres is not and has not been involved in any of the
* frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
- * operations, the status returned is FRSH_NOT_REQUESTED
+ * operations, the status returned is FRSH_RS_NOT_REQUESTED
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
+ * FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
* NULL or the value of the vres argument is not in range \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
* 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 of the calling thread
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
* has been cancelled or it is not valid
- *
+ *
**/
int frsh_vres_get_renegotiation_status
(const frsh_vres_id_t vres,
/*@}*/
////////////////////////////////////////////////////////////////////////
-// CHANGE OF MODE: GROUPS OF CONTRACTS
+// CHANGE OF MODE: GROUPS OF CONTRACTS
////////////////////////////////////////////////////////////////////////
/**
* @defgroup groupofcontracts Group of contracts
* @{
**/
-/**
- * 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_negotiate_group() 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
- * contract situation with removed, changed and added contracts.
+ * contract situation with removed, changed and added contracts.
*
* A successful return code will mean that all contracts have been
* accepted and all required operations (creation, cancellation or
* update of vres) have been carried out to reach the new running
- * context.
+ * 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_negotiate_group() 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,
- const frsh_contract_labels_group_t *new_contract_labels,
- 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);
+/*@}*/
+
////////////////////////////////////////////////////
// OBTAINING INFORMATION FROM THE SCHEDULER
* scheduled under FRSH \n
* FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
* running \n
- * FRSH_ERR_NOT_CONTRACTED_VRESR : if the vres of the calling thread
- * has been cancelled or it is not valid
- *
+ * FRSH_ERR_NOT_CONTRACTED_VRESR : if the vres of the calling thread
+ * has been cancelled or it is not valid
+ *
**/
int frsh_vres_get_usage
(const frsh_vres_id_t vres,
- struct timespec *spent);
+ frsh_rel_time_t *spent);
+
+
+/**
+ * frsh_vres_get_job_usage()
+ *
+ * Get the execution time of the current job of the specified virtual
+ * resource for a bounded or synchronized workload.
+ **/
+int frsh_vres_get_job_usage
+ (const frsh_vres_id_t vres,
+ frsh_rel_time_t *spent);
+
/**
* frsh_vres_get_remaining_budget()
* 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 of the calling thread
- * has been cancelled or it is not valid
- *
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
+ * has been cancelled or it is not valid
+ *
**/
int frsh_vres_get_remaining_budget
(const frsh_vres_id_t vres,
- struct timespec *budget);
+ frsh_rel_time_t *budget);
/**
* 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 of the calling thread
- * has been cancelled or it is not valid
- *
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
+ * has been cancelled or it is not valid
+ *
**/
int frsh_vres_get_budget_and_period
(const frsh_vres_id_t vres,
- struct timespec *budget,
- struct timespec *period);
+ frsh_rel_time_t *budget,
+ frsh_rel_time_t *period);
/*@}*/
*
* This function allows the application to change the period and
* budget of the service thread that makes the
- * negotiations. Increasing the utilization of this thread makes the
+ * negotiations. Increasing the utilization of this thread makes the
* negotiations faster, but introduces additional load in the system
* that may decrease the bandwidth available for the vres. For this
* call, the system will make a schedulability analysis to determine
* the variable pointed to by accepted. If the new service thread data
* is accepted, the system will reassign budgets and periods to the
* vres according to the new bandwidth available, in the same way
- * as it does for a regular contract negotiation.
- *
+ * as it does for a regular contract negotiation.
+ *
* When its budget is exhausted, the service thread may run in the
* background
*
* The service thread starts with a default budget and period that are
* configurable
- *
+ *
* Implementation dependency: in the fixed priority implementtaion of
* frsh, the default priority is lower than the priority of any vres,
* but higher than the background. According to the
* 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 of the calling thread
- * has been cancelled or it is not valid
- *
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
+ * has been cancelled or it is not valid
+ *
**/
-int frsh_service_thread_set_data (const struct timespec *budget,
- const struct timespec *period,
+int frsh_service_thread_set_data (const frsh_rel_time_t *budget,
+ const frsh_rel_time_t *period,
bool *accepted);
/**
* 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 of the calling thread
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
* has been cancelled or it is not valid
- *
+ *
**/
int frsh_service_thread_get_data
- (struct timespec *budget,
- struct timespec *period);
-
+ (frsh_rel_time_t *budget,
+ frsh_rel_time_t *period);
+
/*@}*/
//threads
-
-
+FRSH_CPP_END_DECLS
#endif // _FRSH_CORE_H_
projects / frescor / frsh-include.git / blobdiff