// 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
// **//// /**///** ////////** /**//////**
// ** /** //** /** /** /**
// ** /** //** ******** /** /**
-// // // // //////// // //
+// // // // //////// // //
//
// FRSH(FRescor ScHeduler), pronounced "fresh"
//==============================================
/**
* @file frsh_core.h
- *
- * This file contains the types, definitions and function prototypes
- * for the core module of the First Scheduling Framework.
**/
#include <time.h>
-#include <pthread.h>
#include <sys/types.h>
#include "frsh_core_types.h"
*
* - create a contract and initialize it
* - set/get the basic parameters of a contract
- * - negotiate a service contract, obtaining a server id
- * - create and bind threads to servers
+ * - negotiate a service contract, obtaining a vres id
+ * - create and bind threads to vres
* - create/destroy a synchronization object
* - manage bounded workloads
*
*
* 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, create the threads and, if needed,
- * activate them via some user-specified synchronization mechanism. It
- * may also create a contract for itself. The second time this
- * function is called it fails.
+ * can do the negotiations and create new threads if needed. The
+ * second time this function is called it fails.
*
- * @return
+ * @return 0 if no error. \n
* FRSH_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already
- * been called before
- *
+ * 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_initialize_contract()
- *
- * The operation receives a pointer to a contract parameters object
+ * frsh_contract_init()
+ *
+ * The operation receives a pointer to a contract object
* and initializes it, setting it to the default values.
*
* The default values are:
*
* - resource_id => 0
* - ressource_type => FRSH_CRT_PROCESSOR
- * - contract_id =>
+ * - 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_INDETERMINATE
+ * - d_equals_t => true
* - contract_type => FRSH_CT_REGULAR;
- * - deadline => DEFAULT_DEADLINE;
+ * - deadline => {0,0};
* - budget_overrun_sig_notify => 0; (signal number)
* - budget_overrun_sig_value => {0, NULL};
* - deadline_miss_sig_notify => 0; (signal number)
* - sched_policy => DEFAULT_SCHED_POLICY (FRSH_NONE)
*
* @param contract the pointer to the contract variable.
- *
- * @return FRSH_ERR_BAD_ARGUMENT : contract is NULL
- *
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : contract is NULL
+ *
**/
-int frsh_initialize_contract (frsh_contract_parameters_t *contract);
-
+int frsh_contract_init(frsh_contract_t *contract);
+
/**
- * frsh_set_contract_basic_parameters()
+ * frsh_contract_set_basic_params()
*
* The operation updates the specified contract parameters object by
- * setting its budget, period, and workload and type to the specified
+ * setting its budget, period, workload and type to the specified
* input parameters. (Note: the workload is a basic parameter because
* bounded tasks are triggered by the scheduler (see the
- * frsh_schedule_timed_job() operation), while indeterminate tasks are
- * not; therefore, their programming model is quite different).
+ * frsh_timed_wait() and frsh_synchobj_wait* operations), while
+ * indeterminate tasks are not; therefore, their programming model is
+ * 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,
+ * @param[in] workload the kind of workload (can be FRSH_BOUNDED,
* FRSH_INDETERMINATE or FRSH_OVERHEAD)
* @param[in] contract_type can be FRSH_CT_REGULAR,
* FRSH_CT_BACKGROUND, FRSH_CT_DUMMY.
- *
- * @return 0 if the operation is succesful
+ *
+ * @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
* workload or the contract type values are unknown in the
- * enumerations.
+ * enumerations.
**/
-int frsh_set_contract_basic_parameters
- (frsh_contract_parameters_t *contract,
- const char *contract_id,
- const struct timespec *budget_min,
- const struct timespec *period_max,
- frsh_workload_t workload,
- frsh_contract_type_t contract_type);
-
+int frsh_contract_set_basic_params
+ (frsh_contract_t *contract,
+ const struct timespec *budget_min,
+ const struct timespec *period_max,
+ const frsh_workload_t workload,
+ const frsh_contract_type_t contract_type);
/**
- * frsh_get_contract_basic_parameters()
+ * frsh_contract_get_basic_params()
*
- * This operation obtains from the specified contract parameters
- * object its budget, period, and workload, and copies them to the
- * places pointed to by the corresponding input parameters.
+ * 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.
*
* @param[in] contract the pointer to the contract object
* @param[out] budget_min pointer to preallocated space
* @param[out] workload pointer to preallocated space
* @param[out] contract_type pointer to preallocated space
*
- * @return FRSH_ERR_BAD_ARGUMENT : if one of the contract or
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if one of the contract or
* pointers is NULL.
- *
+ *
**/
-int frsh_get_contract_basic_parameters
- (const frsh_contract_parameters_t *contract,
- char *contract_id,
+int frsh_contract_get_basic_params
+ (const frsh_contract_t *contract,
struct timespec *budget_min,
struct timespec *period_max,
frsh_workload_t *workload,
- frsh_contract_type *contract_type);
+ frsh_contract_type_t *contract_type);
+
+/**
+ * frsh_contract_set_resource_and_label()
+ *
+ * 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 char *contract_label);
+
+
+/**
+ * frsh_contract_get_resource_and_label()
+ *
+ * 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,
+ char *contract_label);
-/**
- * frsh_set_contract_timing_requirements()
+/**
+ * frsh_contract_set_timing_reqs()
*
- * The operation updates the specified contract parameters
- * object, specifying additional time-related requirements.
+ * The operation updates the specified contract object, specifying
+ * 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 posix signal
- * that must be raised if the budget of the server is overrun.
- * If the value of this parameter is 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
- * parameter is set to NULL_SIGNAL.
- * @param [in] deadline_miss_sig_notify contains the number of posix
+ * 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
+ * parameter is set to FRSH_NULL_SIGNAL.
+ * @param [in] deadline_miss_sig_notify contains the number of the
* signal that must be raised if the deadline of the
- * server is missed. If the value of this parameter is
- * NULL_SIGNAL, no signal is raised.
- * @param [in] deadline_miss_sig_value contains the value that will be
+ * 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
* passed to the signal "catcher" when the signal is
- * raised. This parameter is not used if the
- * budget_overrun_sig_notify parameter is set to NULL_SIGNAL
- *
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if contract is NULL or
- * (d_equals_t is true and deadline is not FRSH_NULL_DEADLINE) or
- * (budget_overrun_sig_notify is not a valid signal) or
- * (deadline_miss_sig_notify is not a valid signal) or
- * (d_equals_t is false but (deadline is FRSH_NULL_DEADLINE or its value
+ * raised. This parameter is not used if the
+ * deadline_sig_notify 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
* is grater than the contract's maximum period))
- *
+ *
**/
-int frsh_set_contract_timing_requirements
- (frsh_contract_parameters_t *contract,
- bool d_equals_t,
- const struct timespec *deadline,
- int budget_overrun_sig_notify,
- union sigval budget_overrun_sig_value,
- int deadline_miss_sig_notify,
- union sigval deadline_miss_sig_value);
+int frsh_contract_set_timing_reqs
+ (frsh_contract_t *contract,
+ const bool d_equals_t,
+ const struct timespec *deadline,
+ const frsh_signal_t budget_overrun_signal,
+ const frsh_signal_info_t budget_overrun_siginfo,
+ const frsh_signal_t deadline_miss_signal,
+ const frsh_signal_info_t deadline_miss_siginfo);
/**
- * frsh_get_contract_timing_requirements()
+ * frsh_contract_get_timing_reqs()
*
* The operation obtains the corresponding input parameters from the
- * specified contract parameters object. If d_equals_t is true, the
- * deadline will be set to NULL_DEADLINE.
- *
- * [@return:
- * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
- * ]
- **/
-int frsh_get_contract_timing_requirements
- (const frsh_contract_parameters_t *contract,
+ * specified contract object. If d_equals_t is true, the deadline will
+ * be set to FRSH_NULL_DEADLINE.
+ *
+ * @return 0 if no error \n
+ * 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,
- int *budget_overrun_sig_notify,
- union sigval *budget_overrun_sig_value,
- int *deadline_miss_sig_notify,
- union sigval *deadline_miss_sig_value);
+ frsh_signal_t *budget_overrun_signal,
+ frsh_signal_info_t *budget_overrun_siginfo,
+ frsh_signal_t *deadline_miss_signal,
+ frsh_signal_info_t *deadline_miss_siginfo);
/*@}*/
* @defgroup synch Synchronization objects
* @ingroup core
*
- * Synchronisation objects provide an alternative way for
- * bounded-workload servers to signal the end of their current job and
- * return their remaining budget to FRSH.
+ * 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.
*
* Instead of asking to be reactivated based on an absolute time, they
* queue themselves in a synchronisation object and will wait there
- * until another server (bounded-workload or indeterminate-workload)
+ * 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 servers cannot queue themselves here because
+ *
+ * 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 server.
+ * the objects to activate a waiting workload vres.
*
* For classical signal/wait synchronisation paradigms the application
* must use whatever mechanism the underlying OS provides.
/**
- * frsh_create_synch_obj()
+ * frsh_synchobj_create()
*
* 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
+ *
+ * @param[out] pointer to the variable that will contain the handle to the
* newly created synchronization object
*
- * @return
- * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
- * FRSH_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization
- * objects in the system has already exceeded the maximum
+ * @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
+ * objects in the system has already exceeded the maximum\n
+ * .
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
- * scheduled under the FRSH
+ * scheduled under FRSH\n
+ * .
* FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- *
+ *
**/
-int frsh_create_synch_obj
- (frsh_synch_obj_handle_t *synch_handle);
+int frsh_synchobj_create
+ (frsh_synchobj_handle_t *synch_handle);
/**
- * frsh_destroy_synch_obj()
+ * frsh_synchobj_destroy()
*
* This operation destroys the synchronization object (created by a
* previous call to frsh_create_synch_obj) that is referenced by the
* synch_handle variable can not be used until it is initialized again
* by a call to frsh_create_synch_obj.
*
- * @param synch_handle the handle to the synchronization object
+ * @param synch_handle the handle to the synchronization object
* to be destroyed
*
- * @return 0 if the operation is succesful
- * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
- * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0\n
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid\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
*
- * @sa frsh_create_synch_obj
+ * @sa frsh_synchobj_create
**/
-int frsh_destroy_synch_obj
- (frsh_synch_obj_handle_t synch_handle);
+int frsh_synchobj_destroy
+ (const frsh_synchobj_handle_t synchobj_handle);
/**
- * frsh_schedule_triggered_job()
+ * frsh_synchobj_wait()
*
* This operation is invoked by threads associated with bounded
- * workload servers to indicate that a job has been completed (and
+ * 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 servers).
+ * job to other vres).
*
- * As a difference with frsh_schedule_timed_job(), here the server
+ * 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 server and make it start when a signal operation
- * has been done from another thread.
+ * recently created vres and make it start when a signal operation
+ * has been sent from another thread.
*
- * The server's budget will be made zero for the remainder of the server's
- * period, and the implementation will not replenish the budget until
- * the event has been notified to the specified synchronization object.
+ * The vres' budget will be made zero for the remainder of the vres'
+ * period, and FRSH will not replenish it until an event has been
+ * notified to the synchronisation object by another vres.
*
* It can happen that the synchronisation object has notification
* events queued from the past, in this case one of the events is
- * dequeued immediately and the server won't have to wait for another
+ * dequeued immediately and the vres won't have to wait for another
* one.
*
- * At the time of reception of a notification event (with in the
+ * At the time of reception of a notification event (wether in the
* future or in the past), all pending budget replenishments (if any)
- * are made effective. Once the server has a positive budget and the
+ * are made effective. Once the vres has a positive budget and the
* scheduler schedules the calling thread again, the call returns and
- * at that time.
+ * the vres continues executing.
*
- * If the synchronisation object is destroyed while the server was
- * waiting on it, the server will be awaken and the function will
+ * If the synchronisation object is destroyed while the vres was
+ * waiting on it, the vres will be awaken and the function will
* return with a code FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE
*
* Except for those parameters equal to NULL pointers, the system
- * reports the current period and budget for the current job, whether
- * the deadline of the previous job was missed or not, and whether the
- * budget of the previous job was overrun or not.
+ * 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.
*
* In a system with hierarchical scheduling, since this call makes the
- * budget zero, the other threads in the same server are not run. As
- * mentioned above, only when the call finishes the budget may be
- * replenished.
+ * 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.
*
- * @param synch_handle Synchronisation object upon which the server
+ * @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 server 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 server period upon return (ignored if NULL).
+ * @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
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
+ *
+ * @return 0 if success \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
- * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
- * under the FRSH
- * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
- * server bound to it
- * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
+ * 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
+ * vres bound to it \n
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0 \n
* FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not
- * valid or was destroyed while the server was waiting on it.
- * FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
+ * 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_schedule_triggered_job
- (frsh_synch_obj_handle_t synch_handle,
- struct timespec *next_budget,
- struct timespec *next_period,
- bool *was_deadline_missed,
- bool *was_budget_overran);
+int frsh_synchobj_wait
+ (const frsh_synchobj_handle_t synch_handle,
+ struct timespec *next_budget,
+ struct timespec *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
/**
- * frsh_timed_schedule_triggered_job()
+ * frsh_synchobj_wait_with_timeout()
*
- * This call is the same as frsh_schedule_triggered_job, but with an
+g * 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 a timeout or not
+ * function returned because of the expiration of the timeout or not.
*
- * @return
- * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not valid
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
+ * @return 0 if no error \n
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not
+ * valid \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
- * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
- * under the FRSH
- * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
- * server bound to it
- * 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
- * FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
+ * 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
+ * vres bound to it \n
+ * 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_timed_schedule_triggered_job
- (frsh_synch_obj_handle_t synch_handle,
- const struct timespec *abs_timeout,
- bool *timed_out,
- struct timespec *next_budget,
- struct timespec *next_period,
- bool *was_deadline_missed,
- bool *was_budget_overran);
+int frsh_synchobj_wait_with_timeout
+ (const frsh_synchobj_handle_t synch_handle,
+ const struct timespec *abs_timeout,
+ bool *timed_out,
+ struct timespec *next_budget,
+ struct timespec *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
/**
- * frsh_signal_synch_obj()
+ * frsh_synchobj_signal()
*
* This function sends a notification event to the synchronization object
- * specified as parameter. If there is at least one server waiting on
- * the synchronization object, it is awaken. If more than one server
- * is waiting, just one of them is awaken. However, which one is
- * awaken is implementation dependent. If no server is waiting on the
+ * specified as parameter. If there is at least one vres waiting on
+ * the synchronization object, it is awaken. If more than one vres
+ * are waiting, just one of them is awaken. However, which one is
+ * 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 the operation is completed succesfully
- * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
- * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0 \n
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid \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_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_schedule_triggered_job, frsh_timed_schedule_triggered_job
+ * configuration parameter header file
+ *
+ * @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
**/
-int frsh_signal_synch_obj
- (frsh_synch_obj_handle_t synch_handle);
+int frsh_synchobj_signal
+ (const frsh_synchobj_handle_t synch_handle);
/**
- * frsh_schedule_timed_job()
+ * frsh_timed_wait()
*
* This operation is invoked by threads associated with bounded
- * workload servers to indicate that a job has been completed (and
+ * 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 servers). It is also invoked when the first job of
- * such threads has to be scheduled.
+ * job to other vres). It is also invoked when the first job of
+ * such threads has to be scheduled.
*
- * As an effect, the system will make the current server's budget zero
- * for the remainder of the server's period, and will not replenish
+ * 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
* the budget until the specified absolute time. At that time, all
* pending budget replenishments (if any) are made effective. Once the
- * server has a positive budget and the scheduler schedules the
+ * vres has a positive budget and the scheduler schedules the
* calling thread again, the call returns and at that time, except for
* those parameters equal to NULL pointers, the system reports the
* current period and budget for the current job, whether the deadline
* the previous job was overrun or not.
*
* In a system with hierarchical scheduling, since this call makes the
- * budget zero, the other threads in the same server are not run. As
+ * budget zero, the other threads in the same vres are not run. As
* mentioned abobe, only when the call finishes the budget may be
* replenished.
*
- * (PEPPE: I have a question, what
- * happens to the budget? if I do not get it wrong, the replenishment
- * time is set to abs_time and the bandwidth of the server up to time
- * abs_time can be reassigned. Is it true? what is the exact
- * relationship between this abs_time and the server period? What if
- * the user specifies an abs_time less than the end of the current
- * server period??)
- *
- * @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 server 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 server 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 server 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.
*
* @param [out] was_budget_overrun upon return of this function, the
* variable pointed by this function will be
- * equal to true if the previous server budget was
+ * equal to true if the previous vres budget was
* overrun, to false otherwise. If this
* parameter is set to NULL, no action is
* taken.
*
- * @return 0 if the operation is succesful
- * FRSH_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification
- * is in the past.
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
- * main scheduler
- * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling
- * thread is not scheduled under the FRSH
- * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
- * server bound to it
- * FRSH_ERR_BAD_ARGUMENT : if abs_time is NULL
- * FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
+ * @return 0 if the operation is successful \n
+ * FRSH_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification
+ * is in the past. \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_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_schedule_triggered_job, frsh_timed_schedule_triggered_job
+ *
+ * @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
**/
-int frsh_schedule_timed_job
+int frsh_timed_wait
(const struct timespec *abs_time,
struct timespec *next_budget,
struct timespec *next_period,
* @defgroup negotiate Negotiate contract functions
* @ingroup core
*
- * The following functions are used to create servers for a contract
- * parameters specification and also to assign and unassign threads to
- * servers.
+ * 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.
*
- * In the case of more than one thread per server please refer to the
+ * In the case of more than one thread per vres please refer to the
* hierarchical module.
*
* @{
**/
-/**
- * The type references a function that may become a thread's
- * code
- **/
-typedef void * (*frsh_thread_code_t) (void *);
-
/**
- * frsh_negotiate_contract()
+ * frsh_contract_negotiate()
*
* The operation negotiates a contract and if accepted it will return
- * a server_id. It will also append the contract_id string to the
- * server ot identify it uniquely within a group of servers.
- *
+ * a vres_id. It will also check that the given contract_label is unique
+ * within the node.
+ *
* If the on-line admission test is enabled, it determines whether the
* contract can be admitted or not based on the current contracts
- * established in the system. Then it creates the server and
+ * 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
+ * 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 server, which
- * will be idle until a thread is bound to it.
- *
- * This operation should only be executed by threads that are already
- * bound to an active server and therefore are being scheduled by the
- * frsh scheduler, except during system initialization.
- *
- * @return 0 if successful
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
+ * 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().
+ *
+ * This operation can only be executed by threads that are already
+ * bound to an active vres and therefore are being scheduled by the
+ * frsh scheduler.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_CONTRACT_REJECTED: The contract is not accepted.\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
- * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
- * under the FRSH
- * FRSH_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL
- * FRSH_ERR_TOO_MANY_SERVERS : if there is no space for more servers
- * (the maximum number of them is already reached)
- * FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS : contract_id is not unique,
- *
+ * main scheduler \n
+ * 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_negotiate_contract
- (const frsh_contract_parameters_t *contract,
- frsh_server_id_t *server);
+int frsh_contract_negotiate
+ (const frsh_contract_t *contract,
+ frsh_vres_id_t *vres);
/**
- * frsh_create_and_bind_thread()
+ * frsh_thread_create_and_bind()
*
- * This operation creates a thread and binds it to an existing server.
+ * This operation creates a thread and binds it to an existing vres.
*
* This is the preferred way to add threads to the application because
* we make sure that the thread won't become unbound.
*
- * The server must not have any thread binded to it. If you want to
- * bind more than one thread to the server you must use the
+ * The vres must not have any thread binded to it. If you want to
+ * bind more than one thread to the vres you must use the
* hierarchical module.
*
- * The attr 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.
- *
- * @param[in] server_id Server with which the thread will be bound.
- * @param[out] thread pthread_id returned by the system.
+ * 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.
+ *
+ * @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
* by the system. Ignored if NULL
* @param[in] thread_code Thread function (void func(void *) )
* 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.
- *
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL
- * FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected.
- *
+ * 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
+ * NULL \n
+ * FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected. \n
+ * .
* It may also return all the errors that may be returned by the
- * pthread_create()POSIX function call
- *
+ * fosa_thread_create() function call
+ *
**/
-int frsh_create_and_bind_thread
- (frsh_server_id_t server,
- pthread_t *thread,
- pthread_attr_t *attr,
- frsh_thread_code_t thread_code,
+int frsh_thread_create_and_bind
+ (const frsh_vres_id_t vres,
+ frsh_thread_id_t *thread,
+ frsh_thread_attr_t *attr,
+ frsh_thread_code_t thread_code,
void *arg);
/**
- * frsh_create_thread_in_background()
+ * frsh_thread_create_in_background()
*
* This function creates a "background contract" that does not need to
- * be negotiated, creates a threads and binds to the new server.
+ * be negotiated, creates a threads and binds to the new vres.
*
* This method is suggested as a way to initate components and
* plugins. The event that triggers the component activation should
* @param[in] thread_arg General pointer that will be passed to
* the new thread as initialisation data.
* @param attr Pthread attribute with thread params
- * @param[in] contract_id Contract Id for the new server.
+ * @param[in] contract_label Contract label for the new vres.
* @param[out] thread_id Id of the new thread.
- * @param[out] server_id Server_id of the new server.
- *
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : Any problems with the argument
- * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
- * under the FRSH
- * FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS : contract_id is not unique,
- * FRSH_ERR_TOO_MANY_SERVERS : if there is no space for more servers
+ * @param[out] vres_id vres_id of the new vres.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : Any problems with the argument \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is
+ * not scheduled under FRSH \n
+ * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS : contract_label is not unique \n
+ * FRSH_ERR_TOO_MANY_VRES : if there is no space for more vres
* (the maximum number of them is already reached)
*
**/
-int frsh_create_thread_in_background
+int frsh_thread_create_in_background
(frsh_thread_code_t thread_code,
const void *thread_arg,
- const char *contract_id,
- pthread_attr_t *attr,
- pthread_t *thread_id,
- frsh_server_id_t *server_id);
+ const char *contract_label,
+ frsh_thread_attr_t *attr,
+ frsh_thread_id_t *thread_id,
+ frsh_vres_id_t *vres_id);
/**
- * frsh_bind_thread_to_server()
+ * frsh_thread_bind()
*
- * This operation associates a thread with a server, which means that
- * it starts consuming the server's budget and is executed according
- * to the contract established for that server. If the thread is
- * already bound to another server, it is effectively unbound from it
- * and bound to the specified one.
+ * This operation associates a thread with a vres, which means that
+ * 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.
*
- * It fails if the server's policy is different than FRSH_NONE, or if
- * there is already a thread bound to this server. In order to bind
- * more than one server to the same thread you must use the
+ * 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
+ * more than one vres to the same thread you must use the
* hierarchical module.
*
* Implementation dependent issue: In order to allow the usage of
* scheduling policy SCHED_APP and at the same time be attached to an
* application scheduler different than the frsh scheduler.
*
- * @return
+ * @return 0 if successful \n
* FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
- * main scheduler
+ * main scheduler \n
* FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
- * an application defined scheduler different than the frsh scheduler
- * FRSH_ERR_BAD_ARGUMENT : if the server value does not complain with the
- * expected format or valid range or the given thread does not exist
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
- * FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
- * of the server is FRSH_OVERHEAD
- * FRSH_ERR_ALREADY_BOUND : if the given server has a thread already bound
- *
+ * an application defined scheduler different than the frsh
+ * scheduler \n
+ * FRSH_ERR_BAD_ARGUMENT : if the vres value does not complain with the
+ * expected format or valid range or the given thread does not
+ * exist \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
+ * valid \n
+ * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
+ * of the vres is FRSH_OVERHEAD \n
+ * FRSH_ERR_ALREADY_BOUND : if the given vres has a thread already
+ * bound
+ *
**/
-int frsh_bind_thread_to_server
- (frsh_server_id_t server,
- pthread_t thread);
+int frsh_thread_bind
+ (const frsh_vres_id_t vres,
+ const frsh_thread_id_t thread);
/**
- * frsh_unbind_thread_from_server()
+ * frsh_thread_unbind()
*
- * This operation unbinds a thread from a server. Since threads with
- * no server associated are not allowed to execute, they remain in a
+ * This operation unbinds a thread from a vres. Since threads with
+ * no vres associated are not allowed to execute, they remain in a
* dormant state until they are either eliminated or bound again.
*
* If the thread is inside a critical section the effects of this call
* application scheduler, the thread is still attached to the frsh
* scheduler, but suspended.
*
- * @return 0 if successul
+ * @return 0 if successful \n
* FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
- * main scheduler
- * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist
- * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
- * under 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
+ * under FRSH \n
* FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
- * an application defined scheduler different than the frsh scheduler
- * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
- * server bound to it
+ * 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
**/
-int frsh_unbind_thread_from_server(pthread_t thread);
+int frsh_thread_unbind(const frsh_thread_id_t thread);
/**
- * frsh_get_server()
+ * frsh_thread_get_vres_id()
*
- * This operation stores the Id of the server associated with the
- * specified thread in the variable pointed to by server. It returns
+ * This operation stores the Id of the vres associated with the
+ * specified thread in the variable pointed to by vres. It returns
* an error if the thread does not exist, it is not under the control
* of the scheduling framework, or is not bound.
*
- * @return
- * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
- * under the FRSH
- * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
- * server bound to it
+ * @return 0 if no error \n
+ * 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
+ * vres bound to it \n
* FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist or the
- * server argument is NULL
- *
+ * vres argument is NULL
+ *
**/
-int frsh_get_server(pthread_t thread,
- frsh_server_id_t *server);
+int frsh_thread_get_vres_id(const frsh_thread_id_t thread,
+ frsh_vres_id_t *vres_id);
/**
- * frsh_get_contract()
+ * frsh_vres_get_contract()
*
* This operation stores the contract parameters currently associated
- * with the specified server in the variable pointed to by
- * contract. It returns an error if the server id is incorrect.
+ * with the specified vres in the variable pointed to by
+ * contract. It returns an error if the vres_id is not recognised.
*
- * @return 0 if no error
- * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
- * of the server argument is not in range
+ * @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 the FRSH
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_get_contract
- (frsh_server_id_t server,
- frsh_contract_parameters_t *contract);
+int frsh_vres_get_contract
+ (const frsh_vres_id_t vres,
+ frsh_contract_t *contract);
/**
- * frsh_get_server_contract_id()
+ * frsh_resource_get_vres_from_label()
+ *
+ * This operation retrieves the vres_id whose contract_label
+ * corresponds to the parameter in the resource_id and resource_type
+ * specified.
*
- * This operation retrieves the server_id whose contract_id
- * corresponds to the parameter. It returns an error if the
- * contract_id is not known.
+ * The contract label must refer to a contract negotiated
+ * in the same processing node in which the call is being
+ * made. Otherwise an error is returned.
*
- * @return 0 if no error
+ * @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the
- * contract_id is NULL
+ * contract_label 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
- * FRSH_ERR_CONTRACT_ID_UNKNOWN: if the contract_id is not known
+ * 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
**/
-int frsh_get_server_by_contract_id
- (frsh_contract_id_t contract_id,
- frsh_server_id_t *server);
+int frsh_resource_get_vres_from_label
+ (const char *contract_label,
+ const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
+ frsh_vres_id_t *vres);
/**
- * frsh_cancel_contract()
+ * frsh_contract_cancel()
*
- * The operation eliminates the specified server
+ * The operation eliminates the specified vres
* and recalculates all necessary parameters for the contracts
* remaining in the system. This is a potentially blocking operation;
* it returns when the system has made the changes effective.
*
* Note that the thread is not eliminated. We leave the application
* the option to either freeze it for a later use or bind it to
- * another server.
+ * another vres.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the value of server is not in range
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of vres is not in range \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
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_cancel_contract (frsh_server_id_t server);
+int frsh_contract_cancel (const frsh_vres_id_t vres);
/**
- * frsh_renegotiate_contract_synchronously()
+ * frsh_contract_renegotiate_sync()
*
- * The operation renegotiates a contract for an existing server. If
+ * The operation renegotiates a contract for an existing vres. If
* the on-line admission test is enabled it determines whether the
* contract can be admitted or not based on the current contracts
* established in the system. If it cannot be admitted, the old
* either rejected the new contract, or admitted it and made it
* effective.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL or the
- * value of the server argument is not in range
+ * @return 0 if successful \n
+ * 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 the FRSH
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
- * has been cancelled or it is not valid
+ * 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 \n
* FRSH_ERR_REJECTED_CONTRACT : if the renegotiation fails
- *
+ *
**/
-int frsh_renegotiate_contract_synchronously
- (const frsh_contract_parameters_t *new_contract,
- frsh_server_id_t server);
+int frsh_contract_renegotiate_sync
+ (const frsh_contract_t *new_contract,
+ const frsh_vres_id_t vres);
/**
- * frsh_renegotiate_contract_asynchronously()
+ * frsh_contract_renegotiate_async()
*
* The operation enqueues a renegotiate operation for an existing
- * server, and returns immediately. The renegotiate operation is
+ * vres, and returns immediately. The renegotiate operation is
* performed asynchronously, as soon as it is practical; meanwhile the
* system operation will continue normally. When the renegotiation is
* made, if the on-line admission test is enabled it determines
* 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.
- * When the operation is completed,
- * notification is made to the caller, if requested, via a signal. The
- * status of the operation (in progress, admitted, rejected) can be
- * checked with the get_renegotiation_status operation. The argument
- * sig_notify can be NULL_SIGNAL (no notification), or any posix
- * signal; and in this case sig_value is to be sent with the signal.
+ * 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
+ * progress, admitted, rejected) can be checked with the
+ * frsh_vres_get_renegotiation_status() operation. The argument
+ * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
+ * signal value and in this case signal_info is to be sent with the signal.
*
* @param[in] new_contract New contract parameters for the new
* situation if approved.
- * @server server_id on which to do the
- * renegotiation.
- * sig_notify, sig_value Signal parameters to receive the
- * notification of the result (or
- * NULL_SIGNAL) if we don't want to be notifyed.
- *
- * @return
- * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL, the
- * value of the server argument is not in range or sig_notify is
- * neither NULL nor a valid POSIX signal
+ * @param[in] vres vres_id on which to do the renegotiation.
+ * @param[in] signal_to_notify Signal number to use to notify vres of
+ * the negotiation result. If
+ * 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.
+ *
+ * @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
+ * neither NULL nor a valid POSIX signal \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
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_renegotiate_contract_asynchronously
- (const frsh_contract_parameters_t *new_contract,
- frsh_server_id_t server,
- int sig_notify,
- union sigval sig_value);
+int frsh_contract_renegotiate_async
+ (const frsh_contract_t *new_contract,
+ const frsh_vres_id_t vres,
+ const frsh_signal_t signal_to_notify,
+ const frsh_signal_info_t signal_info);
/**
- * frsh_get_renegotiation_status()
+ * frsh_vres_get_renegotiation_status()
*
* The operation reports on the status of the last renegotiation
- * operation enqueued for the specified server. It is callable even
+ * operation enqueued for the specified vres. It is callable even
* after notification of the completion of such operation, if
- * requested.
+ * requested.
*
- * If the server is not and has not been involved in any of the
- * frsh_request_contract_renegotiation() or frsh_request_renegotiate_new_context()
+ * 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
*
- * @return:
- * FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
- * NULL or the value of the server argument is not in range
+ * @return 0 if no error \n
+ * 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 the FRSH
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_get_renegotiation_status
- (frsh_server_id_t server,
+int frsh_vres_get_renegotiation_status
+ (const frsh_vres_id_t vres,
frsh_renegotiation_status_t *renegotiation_status);
/*@}*/
////////////////////////////////////////////////////////////////////////
-// CHANGE OF MODE: GROUPS OF CONTRACTS
+// CHANGE OF MODE: GROUPS OF CONTRACTS
////////////////////////////////////////////////////////////////////////
/**
* @defgroup groupofcontracts Group of contracts
* The following functions are used to negotiate atomically more than
* one contract. This allows to build complex applications by
* splitting them in individual contracts that are negotiated
- * simultaneously.
+ * simultaneously and atomically.
*
* @{
**/
/**
- * frsh_negotiate_group()
+ * frsh_group_negotiate()
*
* This function negotiates atomically a group of new contracts
* while giving the possibility of cancellling others.
* situation with removed and added contracts.
*
* If the overall negotiation is successful, all actions will be taken
- * inmediatly: the creation of new servers for the contract_up list
+ * 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
*
* @param[in] contracts_up List of new proposed contracts
*
- * @param[in] servers_down List of servers_id to be canceled
+ * @param[in] vres_down List of vres_id to be canceled
*
- * @param[out] servers_up Servers_id assigned by the system to the
+ * @param[out] vres_up vres_id assigned by the system to the
* corresponding contracts_up.
*
- * @return 0 if no error
- *
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
+ * @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
- * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
- * under the FRSH
- * FRSH_ERR_BAD_ARGUMENT : if any of the servers_up or accepted arguments
- * is NULL, if the contracts_up and servers_down arguments are both NULL,
+ * 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_negotiate_group
+int frsh_group_negotiate
(const frsh_contracts_group_t *contracts_up,
- const frsh_servers_group_t *servers_down,
- frsh_servers_group_t *servers_up);
+ const frsh_vres_group_t *vres_down,
+ frsh_vres_group_t *vres_up);
/**
- * frsh_change_mode_synchronously()
+ * 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_negotiate_group() in order to
- * better grasp possible issues that the problem may raise.
+ * having fully implemented frsh_group_negotiate() in order to
+ * better grasp possible issues that the problems it may raise.
*
* This is a draft of the specification, it is yet subject to
- * change.
+ * change.
*
* 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.
*
* If the on-line admission test is enabled, FRSH analizes the
- * schedulability of the context that results in the new contract
- * situation with removed change and added contracts.
+ * schedulability of the context that would result in the new
+ * 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 servers) have been carried out to reach the new running
- * context.
+ * 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
* and made them effective. There is also an asynchronous
* (non-blocking) version of this function below.
*
- * @param[in] contracts_new_servers Contracts for new servers to be
- * added.
- * @param[out] servers_id_new Server_id's corresponding to the new
+ * @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_servers New contracts for servers to
+ * @param[in] contracts_update_vres New contracts for vres to
* be updated.
- * @param[in] servers_update Server_id's corresponding to the
+ * @param[in] vres_update vres_id's corresponding to the
* contracts that have to be updated.
- * @param[in] servers_removed Server_id's to be removed.
+ * @param[in] vres_removed Vres_id's to be removed.
*
- * @return
- * FRSH_ERR_BAD_ARGUMENT Invalid pointer or server_id ranges.
- * FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS contract_id not unique.
- * FRSH_ERR_NOT_CONTRACTED_SERVER: One of the provided
- * server_id's is not recognised.
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT Invalid pointer or vres_id ranges. \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.
+ * is not scheduled under FRSH. \n
* FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong
- * or not running.
+ * or not running. \n
* FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
- * FRSH main scheduler.
+ * FRSH main scheduler. \n
* FRSH_ERR_REJECTED_CONTRACT: The negotiation of one of the
* proposed contracts has failed.
- *
+ *
**/
-int frsh_change_mode_synchronously
- (const frsh_contracts_group_t *contracts_new_servers,
- frsh_servers_group_t *servers_id_new,
- const frsh_contracts_group_t *contracts_update_servers,
- const frsh_servers_group_t *servers_update,
- const frsh_servers_group_t *servers_removed);
+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);
/**
- * frsh_change_mode_asynchronously()
+ * frsh_group_change_mode_async()
*
* This operation enqueues a global renegotiation of a group of
- * contracts (with a possible addition of new servers) and returns
+ * contracts (with a possible addition of new vres) and returns
* immediately. The renegotiation is performed asynchronously as soon
- * as it is practical.
+ * 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.
+ * change.
*
* This is an asynchronous (non-blocking) version of
- * frsh_negotiate_new_running_context(). Note however that there must
+ * 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_get_renegotiation_status() invoked for any of
- * the servers involved in the renegotiation (updated or to be
- * removed). As an option, a signal can be sent to the caller to
+ * 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_servers Contracts for new servers to be
+ *
+ * @param[in] contracts_new_vres Contracts for new vres to be
* added.
- * @param[in] contract_ids Contract id's for the corresponding new
- * servers to be added.
- * @param[out] servers_id_new Server_id's corresponding to the new
+ * @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_servers New contracts for servers to
+ * @param[in] contracts_update_vres New contracts for vres to
* be updated.
- * @param[in] servers_update Server_id's corresponding to the
+ * @param[in] vres_update vres_id's corresponding to the
* contracts that have to be updated.
- * @param[in] servers_removed Server_id's to be removed.
+ * @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.
- *
- * @return
- * FRSH_ERR_BAD_ARGUMENT Invalid pointer or server_id ranges. Also
- * when the request is for adding only new contracts.
- * FRSH_ERR_CONTRACT_ID_ALREADY_EXISTS contract_id not unique.
- * FRSH_ERR_NOT_CONTRACTED_SERVER: One of the provided
- * server_id's is not recognised.
+ *
+ * @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_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_SCHEDULED_CALLING_THREAD The calling thread
- * is not scheduled under FRSH.
+ * is not scheduled under FRSH. \n
* FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong
- * or not running.
+ * or not running. \n
* FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
- * FRSH main scheduler.
+ * FRSH main scheduler. \n
* FRSH_ERR_REJECTED_CONTRACT: The negotiation of one of the
* proposed contracts has failed.
**/
-int frsh_change_mode_asynchronously
- (const frsh_contracts_group_t *contracts_new_servers,
- const frsh_contract_ids_group_t *contract_ids,
- frsh_servers_group_t *servers_id_new,
- const frsh_contracts_group_t *contracts_update_servers,
- const frsh_servers_group_t *servers_update,
- const frsh_servers_group_t *servers_removed,
- int sig_notify,
- union sigval sigvalue);
+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);
/*@}*/
/**
- * frsh_is_admission_test_enabled()
+ * frsh_config_is_admission_test_enabled()
*
* Returns true if the system is
* configured with the on-line admission test enabled, or false
* otherwise. This situation can only be changed at compile time.
**/
-bool frsh_is_admission_test_enabled();
+bool frsh_config_is_admission_test_enabled();
/**
- * frsh_get_resource_usage()
+ * frsh_vres_get_usage()
*
* This function stores the current execution time spent by the
- * threads bound to the specified server in the variable pointed to by
+ * threads bound to the specified vres in the variable pointed to by
* cpu_time.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- * cpu_time is NULL
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
+ * cpu_time 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
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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
- *
+ *
**/
-int frsh_get_resource_usage
- (frsh_server_id_t server,
+int frsh_vres_get_usage
+ (const frsh_vres_id_t vres,
struct timespec *spent);
/**
- * frsh_get_remaining_budget()
+ * frsh_vres_get_remaining_budget()
*
* This function stores in the variable pointed to by budget the
* remaining execution-time budget associated with the specified
- * server
+ * vres.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- * budget is NULL
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
+ * budget 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
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_get_remaining_budget
- (frsh_server_id_t server,
+int frsh_vres_get_remaining_budget
+ (const frsh_vres_id_t vres,
struct timespec *budget);
/**
- * frsh_get_budget_and_period()
+ * frsh_vres_get_budget_and_period()
*
* This function stores in the variables
* pointed to by budget and period, the execution-time budget and the
- * period respectively associated with the specified server. If any of
+ * period respectively associated with the specified vres. If any of
* these pointers is NULL, the corresponding information is not stored.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
- * or budget and period are both NULL
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
+ * or budget and period are both 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
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_get_budget_and_period
- (frsh_server_id_t server,
+int frsh_vres_get_budget_and_period
+ (const frsh_vres_id_t vres,
struct timespec *budget,
struct timespec *period);
**/
/**
- * frsh_set_service_thread_data()
+ * frsh_service_thread_set_data()
*
- * This function allows the application to
- * change the period and budget of the service thread that makes the
+ * 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 faster, but introduces additional load in the system
- * that may decrease the bandwidth available for the servers. For this
- * call, the system will make a schedulability analysis to determine if
- * the new situation is acceptable or not. This is reported back in the
- * variable pointed to by accepted. If the new service thread data is
- * accepted, the system will reassign budgets and periods to the
- * servers according to the new bandwidth available, in the same way as
- * it does for a regular contract negotiation.
- *
+ * that may decrease the bandwidth available for the vres. For this
+ * call, the system will make a schedulability analysis to determine
+ * if the new situation is acceptable or not. This is reported back in
+ * 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.
+ *
* 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 server,
+ * frsh, the default priority is lower than the priority of any vres,
* but higher than the background. According to the
* implementation-dependent module the priority is adjustable by means
* of a function that changes its preemption level
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
- * the budget value is greater than the period value
+ * the budget value is greater than the period value \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
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_set_service_thread_data (const struct timespec *budget,
+int frsh_service_thread_set_data (const struct timespec *budget,
const struct timespec *period,
bool *accepted);
/**
- * frsh_get_service_thread_data()
+ * frsh_service_thread_get_data()
*
* this function returns in the variables pointed by budget and
* period, respectively, the current budget and period of the service
* thread.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments 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
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
+ * 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_get_service_thread_data
+int frsh_service_thread_get_data
(struct timespec *budget,
struct timespec *period);
-
+
/*@}*/
//A round-robin background scheduling policy is available for those
//threads that do not have real-time requirements. Because some of
//these threads may require sharing information with other threads run
-//by regular servers, special background contracts may be created for
+//by regular vres. Special background contracts may be created for
//specifying the synchronization requirements.
-//The way of specifying a background contract is by setting budget_min
-//= period_max = 0. Negotiation may fail if the contract uses
+//The way of specifying a background contract is by setting
+//contract_type to FRSH_CT_BACKGROUND. Negotiation may fail if the contract uses
//shared_objects. If the contract has no shared_objects the returned
-//server id represents the background and may be used to bind more
-//than one thread. If the contract has shared objects a server is
+//vres id represents the background and may be used to bind more
+//than one thread. If the contract has shared objects a vres is
//created to keep track of them, but the associated threads are
//executed in the background, together with the other background
//threads