// Basic FRSH(FIRST Scheduling Framework) contract management
//================================================================
-/**
- \defgroup core Core module
-
- This module includes the basic functions and services that are
- provided by any FRSH implementation. This module includes basic type
- definitions, and functions to
-
- - 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
- - create/destroy a synchronization object
- - manage bounded workloads
-*/
-/*@{*/
-
/**
\file frsh_core.h
-/**
- This function converts an error code to an error message that is
- stored in the buffer starting at the location pointed to by
- message. The size of this buffer is specified by the size
- argument. If the error message is longer than size-1, it is
- truncated to that length. Regardless of whether the message is
- truncated or not, a final zero character that marks the end of the
- string is stored in the buffer. The function fails if the error
- code passed does not correspond to any of the frsh error codes.
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : error is not a valid value
- ]
-*/
int frsh_strerror (int error, char *message, size_t size);
+
+//////////////////////////////////////////////////////////////////////
+// INITIALIZATION SERVICES
+//////////////////////////////////////////////////////////////////////
+
+/**
+ \defgroup initialization Initialization services
+
+ These functions need to be called before doing any FRSH operation
+ (including contract initialization).
+
+*/
+/*@{*//
+
+
+/**
+ * frsh_init()
+ *
+ * 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.
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already
+ * been called before
+ *
+ * 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();
+
+/*@}*/
+
+
/////////////////////////////////////////////////////////////
// CONTRACT PARAMETERS
/////////////////////////////////////////////////////////////
-
/**
- \defgroup contract Contract Creation and Initialization.
-
- These functions are used to create and initialize a contract, and
- set its parameters.
+ * \defgroup contract Contract Creation and Initialization.
+ *
+ * These functions are used to create and initialize a contract, and
+ * set its parameters.
+ **/
+
+/* FUNCTION LIST
+ *
+ * frsh_initialize_contract()
+ *
+ * frsh_set_contract_basic_parameters()
+ *
+ *
*/
/*@{*/
-/**
- Contract parameters type; it is an opaque type (i.e. the internal
- structure of this data type is implementation dependent). The user
- can access and modify the parameters of a contract only with the
- proper functions, and should never access the data directly.
-*/
-typedef FRSH_CONTRACT_PARAMETERS_T_OPAQUE frsh_contract_parameters_t;
/**
- The operation receives a pointer to a contract parameters object
- and initializes it, setting it to the default values.
- The default values are:
- - budget min and max are set to 0
- - period min and max are set to 0
- - the workload is unbounded (FRSH_INDETERMINATE)
- - the server deadline is equal to the period
- - the budget and deadline overrun are not notified
- - the granularity is set to "continuous"
- - the quality and importance are set to the default values
- (PEPPE: implementation dependent??)
- - the scheduling policy is FRSH_NONE
-
- @param contract the pointer to the contract variable.
- @returns (PEPPE: should not return anything! change to void??)
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : contract is NULL
- ]
-*/
-int frsh_initialize_contract (frsh_contract_parameters_t *contract);
-
-// budget_min => {0,0};
-// period_max => {0,0};
-// budget_max => {0,0};
-// period_min => {0,0};
-// workload => DEFAULT_WORKLOAD;
-
-// d_equals_t => DEFAULT_D_EQUALS_T; (false or true)
-// 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};
-//
-// granularity => DEFAULT_GRANULARITY;
-// utilization_set; => size = 0
-// quality => DEFAULT_QUALITY; (range 0..100)
-// importance => DEFAULT_IMPORTANCE; (range 1..5)
-//
-// preemption_level => 0; (range 1..2**32-1)
-// critical_sections; => size = 0
+ * Contract parameters type; it is an opaque type (i.e. the internal
+ * structure of this data type is implementation dependent). The user
+ * can access and modify the parameters of a contract only with the
+ * proper functions, and should never access the data directly.
+ **/
+typedef FRSH_CONTRACT_PARAMETERS_T_OPAQUE frsh_contract_parameters_t;
-// sched_policy => DEFAULT_SCHED_POLICY
-// (FRSH_NONE)
+/**
+ * frsh_initialize_contract()
+ *
+ * The operation receives a pointer to a contract parameters object
+ * and initializes it, setting it to the default values.
+ *
+ * The default values are:
+ *
+ * - 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)
+ * - 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};
+ *
+ * - granularity => DEFAULT_GRANULARITY;
+ * - utilization_set; => size = 0
+ * - quality => DEFAULT_QUALITY; (range 0..100)
+ * - importance => DEFAULT_IMPORTANCE; (range 1..5)
+ * - preemption_level => 0; (range 1..2**32-1)
+ * - critical_sections; => size = 0
+ *
+ * - sched_policy => DEFAULT_SCHED_POLICY (FRSH_NONE)
+ *
+ * @param contract the pointer to the contract variable.
+ * @returns (PEPPE: should not return anything! change to void??)
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : contract is NULL
+ * ]
+ **/
+int frsh_initialize_contract (frsh_contract_parameters_t *contract);
+
-/**
- The operation updates the specified contract parameters object by
- setting its budget, period, and workload 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).
-
- @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)
-
- @returns 0 if the operation is succesful
- @returns FRSH_ERR_BAD_ARGUMENT if some of the arguments is not in
- the expected range
- [ERR@RETURNED:
- 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
- is not a proper value (FRSH_INDETERMINATE, FRSH_BOUNDED, or FRSH_OVERHEAD)
- ]
-*/
-int
-frsh_set_contract_basic_parameters
+/**
+ * frsh_set_contract_basic_parameters()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its budget, period, and workload 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).
+ *
+ * @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)
+ *
+ * @returns 0 if the operation is succesful
+ * @returns FRSH_ERR_BAD_ARGUMENT if some of the arguments is not in
+ * the expected range
+ *
+ * [ERR@RETURNED:
+ * 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
+ * is not a proper value (FRSH_INDETERMINATE, FRSH_BOUNDED, or FRSH_OVERHEAD)
+ * ]
+ **/
+int frsh_set_contract_basic_parameters
(frsh_contract_parameters_t *contract,
const struct timespec *budget_min,
const struct timespec *period_max,
/**
- 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.
-
- @param [in] contract the pointer to the contract object
- @param[out] budget_min pointer to the variable that will contain
- the minimum budget
- @param[out] period_max pointer to the variable that will contain the
- max_period
- @param[out] workload pointer to the variable that will contain the
- workload type
-
- @returns (PEPPE: this should return nothing!)
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if contract is NULL
- ]
-*/
-int
-frsh_get_contract_basic_parameters
+ * frsh_get_contract_basic_parameters()
+ *
+ * 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.
+ *
+ * @param [in] contract the pointer to the contract object
+ * @param[out] budget_min pointer to the variable that will contain
+ * the minimum budget
+ * @param[out] period_max pointer to the variable that will contain the
+ * max_period
+ * @param[out] workload pointer to the variable that will contain the
+ * workload type
+ *
+ * @returns (PEPPE: this should return nothing!)
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
+ * ]
+ **/
+int frsh_get_contract_basic_parameters
(const frsh_contract_parameters_t *contract,
struct timespec *budget_min,
struct timespec *period_max,
/**
- The operation updates the specified contract parameters
- object, specifying the additional parameters requirements of
- a contract.
-
- @param contract The pointer to the contract object
-
- @param [in] d_equals_t It is a boolean value, set to true (1) if the
- we want to specify a deadline different from the period
- for the contract.
- @param [in] deadline If the previous parameter is set to true,
- this parameter should be set to NULL_DEADLINE. Otherwise,
- it contains the desired deadline value.
- (PEPPE: should be return with error otherwise?)
- @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
- parameters is set to NULL_SIGNAL.
- @param [in] deadline_miss_sig_notify contains the number of posix
- 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
- passed to the signal "catcher" when the signal is raised.
- This parameters is not used if the budget_overrun_sig_notify
- parameters is set to NULL_SIGNAL
-
- @returns 0 if the operation is succesful
- @returns FRSH_BAD_ARGUMENT if some argument is out of range or not
- admissible.
- [ERR@RETURNED:
- 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
- is grater than the contract´s maximum period)))
- ]
-
- @see sigexplanation
-*/
-int
-frsh_set_contract_timing_requirements
+ * frsh_set_contract_timing_requirements()
+ *
+ * The operation updates the specified contract parameters
+ * object, specifying the additional parameters requirements of
+ * a contract.
+ *
+ * @param contract The pointer to the contract object
+ *
+ * @param [in] d_equals_t It is a boolean value, set to true (1) if the
+ * we want to specify a deadline different from
+ * the period for the contract.
+ * @param [in] deadline If the previous parameter is set to true,
+ * this parameter should be set to
+ * NULL_DEADLINE. Otherwise, it contains the
+ * desired deadline value.
+ * (PEPPE: should be return with error
+ * otherwise?)
+ * @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
+ * 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
+ * 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
+ *
+ * @returns 0 if the operation is succesful
+ * @returns FRSH_BAD_ARGUMENT if some argument is out of range or not
+ * admissible.
+ *
+ * [ERR@RETURNED:
+ * 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
+ * is grater than the contract´s maximum period))
+ * ]
+ *
+ * @see sigexplanation
+ **/
+int frsh_set_contract_timing_requirements
(frsh_contract_parameters_t *contract,
bool d_equals_t,
const struct timespec *deadline,
union sigval deadline_miss_sig_value);
/**
- The operation obtains the corresponding input parameters from the
- specified contract parameters object. If d_equals_t is true, the
- deadline will not be updated.
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if contract is NULL
- ]
-
-*/
-int
-frsh_get_contract_timing_requirements
+ * frsh_get_contract_timing_requirements()
+ *
+ * The operation obtains the corresponding input parameters from the
+ * specified contract parameters object. If d_equals_t is true, the
+ * deadline will not be updated.
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
+ * ]
+ **/
+int frsh_get_contract_timing_requirements
(const frsh_contract_parameters_t *contract,
bool *d_equals_t,
struct timespec *deadline,
//////////////////////////////////////////////////////////////////
// SYNCHRONIZATION OBJECTS
//////////////////////////////////////////////////////////////////
-
-
/**
- \defgroup synch Synchronization objects
-*/
+ * \defgroup synch Synchronization objects
+ *
+ * In the future we may add a broadcast operation that would signal a
+ * group of synchronization objects. We have not included a broadcast
+ * service in this version because it can be easily created by the
+ * user by signalling individual synchronization objects inside a
+ * loop.
+ *
+ * Notice that for synchronization objects there is no naming service
+ * like in shared objects because tasks that use synchronization are
+ * not developed independently, as they are closely coupled.
+ **/
/*@{*/
+
+
/**
- An abstract synchronization object is defined by the application.
- This object can be used by an application to wait for an event to
- arrive by invoking the frsh_schedule_triggered_job() operation. It
- can also be used to signal the event either causing a waiting
- server to wake up, or the event to be queued if no server is
- waiting for it.
-*/
+ * An abstract synchronization object is defined by the application.
+ * This object can be used by an application to wait for an event to
+ * arrive by invoking the frsh_schedule_triggered_job() operation. It
+ * can also be used to signal the event either causing a waiting
+ * server to wake up, or the event to be queued if no server is
+ * waiting for it.
+ **/
typedef FRSH_SYNCH_OBJ_HANDLE_T_OPAQUE frsh_synch_obj_handle_t;
/**
- 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
-
- @returns 0 if the operation is succesful
- @returns FRSH_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
- objects in the system has already exceeded the maximum
- [ERR@RETURNED:
- 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
- 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
- ]
-
-*/
-int
-frsh_create_synch_obj
+ * frsh_create_synch_obj()
+ *
+ * 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
+ *
+ * @returns 0 if the operation is succesful
+ * @returns FRSH_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
+ * objects in the system has already exceeded the maximum
+ *
+ * [ERR@RETURNED:
+ * 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
+ * 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
+ * ]
+ **/
+int frsh_create_synch_obj
(frsh_synch_obj_handle_t *synch_handle);
/**
- This function sends a notification to the synchronization object
- specified as parameter. If there is at least one thread waiting on
- the synchronization object, it is awaken. If more than one thread
- is waiting, just one of them is awaken. However, which one is
- awaken is implementation dependent. If no thread is waiting on the
- synchronization object, the notification is queued.
-
- [JULIO: all the ocurrrences of the word "thread" should be changed
- by "server" in the paragraph above
- ]
- @param [in] synch_handle the handle of the synchronization object to
- notify.
-
- @returns 0 if the operation is completed succesfully
- @returns FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
- FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
- 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_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
-*/
-int
-frsh_signal_synch_obj
+ * frsh_signal_synch_obj()
+ *
+ * This function sends a notification 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
+ * synchronization object, the notification is queued.
+ *
+ * @param [in] synch_handle the handle of the synchronization object to
+ * notify.
+ *
+ * @returns 0 if the operation is completed succesfully
+ * @returns FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
+ * 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_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
+ **/
+int frsh_signal_synch_obj
(frsh_synch_obj_handle_t synch_handle);
+
/**
- This operation destroys the synchronization object (created by a
- previous call to frsh_create_synch_obj) 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.
-
- @param synch_handle the handle to the synchronization object
- to be destroyed
-
- @returns 0 if the operation is succesful
- @returns FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
- FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
- 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
- ]
-
- @sa frsh_create_synch_obj
-*/
-int
-frsh_destroy_synch_obj
+ * frsh_destroy_synch_obj()
+ *
+ * This operation destroys the synchronization object (created by a
+ * previous call to frsh_create_synch_obj) 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.
+ *
+ * @param synch_handle the handle to the synchronization object
+ * to be destroyed
+ *
+ * @returns 0 if the operation is succesful
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
+ * 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
+ * ]
+ *
+ * @sa frsh_create_synch_obj
+ **/
+int frsh_destroy_synch_obj
(frsh_synch_obj_handle_t synch_handle);
-// In the future we may add a broadcast operation that would signal a
-// group of synchronization objects. We have not included a broadcast
-// service in this version because it can be easily created by the
-// user by signalling individual synchronization objects inside a
-// loop.
-
-// Notice that for synchronization objects there is no naming service
-// like in shared objects because tasks that use synchronization are
-// not developed independently, as they are closely coupled.
+/*@}*/
////////////////////////////////////////////////////
// SCHEDULING BOUNDED WORKLOADS
////////////////////////////////////////////////////
-
/**
- This operation is invoked by threads associated with bounded
- workload servers 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. (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??)
-
- 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
- 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
- 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
- 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 abobe, only when the call finishes the budget may be
- replenished.
-
- @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
- 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
- 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
- overrun, to false otherwise. If this
- parameter is set to NULL, no action is
- taken.
-
- @returns 0 if the operation is succesful
- @returns FRSH_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification
- is in the past.
- [ERR@RETURNED:
- 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
- is not FRSH_BOUNDED
- ]
-
- @sa frsh_schedule_triggered_job, frsh_timed_schedule_triggered_job
+ * \defgroup sched_bounded_workloads Scheduling bounded workloads
+ **/
+/*@{*/
-*/
-int
-frsh_schedule_timed_job
+/**
+ * frsh_schedule_timed_job()
+ *
+ * This operation is invoked by threads associated with bounded
+ * workload servers 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. (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??)
+ *
+ * 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
+ * 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
+ * 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
+ * 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 abobe, only when the call finishes the budget may be
+ * replenished.
+ *
+ * @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
+ * 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
+ * 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
+ * overrun, to false otherwise. If this
+ * parameter is set to NULL, no action is
+ * taken.
+ *
+ * @returns 0 if the operation is succesful
+ * @returns FRSH_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification
+ * is in the past.
+ * [ERR@RETURNED:
+ * 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
+ * is not FRSH_BOUNDED
+ * ]
+ *
+ * @sa frsh_schedule_triggered_job, frsh_timed_schedule_triggered_job
+ **/
+int frsh_schedule_timed_job
(const struct timespec *abs_time,
struct timespec *next_budget,
struct timespec *next_period,
/**
- This operation is invoked by threads associated with bounded
- workload servers 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. If the specified synchronization
- object has events queued, one of them is dequeued; otherwise the
- server will wait upon the specified synchronization object, 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 specified synchronization object is signalled. At that time,
- all pending budget replenishments (if any) are made effective. Once
- the server 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
- 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.
-
- [ERR@RETURNED:
- 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 synch_handle is 0
- FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not valid
- FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
- is not FRSH_BOUNDED
- ]
-
-
-*/
-int
-frsh_schedule_triggered_job
+ * frsh_schedule_triggered_job()
+ *
+ * This operation is invoked by threads associated with bounded
+ * workload servers 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. If the specified synchronization
+ * object has events queued, one of them is dequeued; otherwise the
+ * server will wait upon the specified synchronization object, 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 specified synchronization object is signalled. At that time,
+ * all pending budget replenishments (if any) are made effective. Once
+ * the server 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
+ * 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.
+ *
+ * [ERR@RETURNED:
+ * 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 synch_handle is 0
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not valid
+ * FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
+ * is not FRSH_BOUNDED
+ * ]
+ **/
+int frsh_schedule_triggered_job
(frsh_synch_obj_handle_t synch_handle,
struct timespec *next_budget,
struct timespec *next_period,
/**
- This call is the same as frsh_schedule_triggered_job, but with an
- absolute timeout. The timed_out argument, indicates whether the
- function returned because of a timeout or not
-
- [ERR@RETURNED:
- 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
- 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
- is not FRSH_BOUNDED
- ]
-
-*/
-int
-frsh_timed_schedule_triggered_job
+ * frsh_timed_schedule_triggered_job()
+ *
+ * This call is the same as frsh_schedule_triggered_job, but with an
+ * absolute timeout. The timed_out argument, indicates whether the
+ * function returned because of a timeout or not
+ *
+ * [ERR@RETURNED:
+ * 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
+ * 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
+ * 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,
bool *was_budget_overran);
-
-
/*@}*/
///////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////
/**
- \defgroup negotiate Negotiate contract functions
-
- The following functions are used to create servers for a contract
- parameters specification and also to assign one or more threads to
- a server (Note: the current implementation only supports one thread
- per server; this limitation will be removed in the next phase of
- the project)
+ * \defgroup negotiate Negotiate contract functions
+ *
+ * The following functions are used to create servers for a contract
+ * parameters specification and also to assign one or more threads to
+ * a server (Note: the current implementation only supports one thread
+ * per server; this limitation will be removed in the next phase of
+ * the project)
*/
/*@{*/
/**
- Server Id type, that identifies a server created to manage a given
- contract
-*/
+ * Server Id type, that identifies a server created to manage a given
+ * contract
+ **/
typedef int frsh_server_id_t; // => 0
/**
- The type references a function that may become a thread's
- code
-*/
+ * The type references a function that may become a thread's
+ * code
+ **/
typedef void * (*frsh_thread_code_t) (void *);
/**
- The operation negotiates a contract for a new server. 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
- recalculates all necessary parameters for the contracts already
- 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. It returns zero and places the
- server identification number in the location pointed to by the
- server input parameter if accepted, or an error if rejected. No
- thread is bound to the newly created server, which will be idle
- until a thread is bound to it. This operation can only be executed
- by threads that are already bound to an active server and therefore
- are being scheduled by the frsh scheduler.
-
- [ERR@RETURNED:
- 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_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)
- ]
-
-*/
-int
-frsh_negotiate_contract
+ * frsh_negotiate_contract()
+ *
+ * The operation negotiates a contract for a new server. 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
+ * recalculates all necessary parameters for the contracts already
+ * 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. It returns zero and places the
+ * server identification number in the location pointed to by the
+ * server input parameter if accepted, or an error if rejected. No
+ * thread is bound to the newly created server, which will be idle
+ * until a thread is bound to it. This operation can only be executed
+ * by threads that are already bound to an active server and therefore
+ * are being scheduled by the frsh scheduler.
+ *
+ * [ERR@RETURNED:
+ * 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_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)
+ * ]
+ **/
+int frsh_negotiate_contract
(const frsh_contract_parameters_t *contract,
frsh_server_id_t *server);
-
/**
- This operation negotiates a contract for a new server, creates a
- thread and binds it to the server. If the contract is accepted, the
- operation creates a thread with the arguments thread, attr,
- thread_code and arg as they are defined for the pthread_create()
- POSIX function call, and attaches it to the frsh scheduler. Then, it
- binds the created thread to the new server. It returns zero and
- puts the server identification number in the location pointed to by
- the server input parameter. 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. If the contract is
- rejected, the thread is not created and the corresponding error is
- returned.
-
- The server is created with the FRSH_NONE scheduling policy, which
- means no hierarchical scheduling, and only one thread per server,
- except for the case of background tasks (see below)
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL
- FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected.
- FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
- in the contract is FRSH_OVERHEAD
-
- It may also return all the errors that may be returned by the
- pthread_create()POSIX function call
- ]
-
-*/
-int
-frsh_negotiate_contract_for_new_thread
+ * frsh_negotiate_contract_for_new_thread()
+ *
+ * This operation negotiates a contract for a new server, creates a
+ * thread and binds it to the server. If the contract is accepted, the
+ * operation creates a thread with the arguments thread, attr,
+ * thread_code and arg as they are defined for the pthread_create()
+ * POSIX function call, and attaches it to the frsh scheduler. Then, it
+ * binds the created thread to the new server. It returns zero and
+ * puts the server identification number in the location pointed to by
+ * the server input parameter. 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. If the contract is
+ * rejected, the thread is not created and the corresponding error is
+ * returned.
+ *
+ * The server is created with the FRSH_NONE scheduling policy, which
+ * means no hierarchical scheduling, and only one thread per server,
+ * except for the case of background tasks (see below)
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL
+ * FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected.
+ * FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
+ * in the contract is FRSH_OVERHEAD
+ *
+ * It may also return all the errors that may be returned by the
+ * pthread_create()POSIX function call
+ * ]
+ **/
+int frsh_negotiate_contract_for_new_thread
(const frsh_contract_parameters_t *contract,
frsh_server_id_t *server,
pthread_t *thread,
void *arg);
/**
- This operation negotiates a contract for a new server, and binds
- the calling thread to it. If the contract is accepted it returns
- zero and copies the server identification number in the location
- pointed to by the server input parameter. If it is rejected, an
- error is returned.
-
- The server is created with the FRSH_NONE scheduling policy, which
- means no hierarchical scheduling, and only one thread per server,
- except for the case of background tasks (see below)
-
- Implementation dependent issue: In order to allow the usage of
- application defined schedulers, the calling thread must not have
- the SCHED_APP scheduling policy and at the same time be attached to
- an application scheduler different than the frsh scheduler; in such
- case, an error is returned. After a successful call the calling
- thread will have the SCHED_APP scheduling policy and will be
- attached to the frsh scheduler.
-
- [ERR@RETURNED:
- 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 contract or server arguments are NULL
- FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected.
- FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
- in the contract is FRSH_OVERHEAD
- ]
-
-*/
-int
-frsh_negotiate_contract_for_myself
+ * frsh_negotiate_contract_for_myself()
+ *
+ * This operation negotiates a contract for a new server, and binds
+ * the calling thread to it. If the contract is accepted it returns
+ * zero and copies the server identification number in the location
+ * pointed to by the server input parameter. If it is rejected, an
+ * error is returned.
+ *
+ * The server is created with the FRSH_NONE scheduling policy, which
+ * means no hierarchical scheduling, and only one thread per server,
+ * except for the case of background tasks (see below)
+ *
+ * Implementation dependent issue: In order to allow the usage of
+ * application defined schedulers, the calling thread must not have
+ * the SCHED_APP scheduling policy and at the same time be attached to
+ * an application scheduler different than the frsh scheduler; in such
+ * case, an error is returned. After a successful call the calling
+ * thread will have the SCHED_APP scheduling policy and will be
+ * attached to the frsh scheduler.
+ *
+ * [ERR@RETURNED:
+ * 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 contract or server arguments are NULL
+ * FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected.
+ * FRSH_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
+ * in the contract is FRSH_OVERHEAD
+ * ]
+ **/
+int frsh_negotiate_contract_for_myself
(const frsh_contract_parameters_t *contract,
frsh_server_id_t *server);
/**
- frsh_bind_thread_to_server: 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.
-
- It fails if the server's policy is different than FRSH_NONE, or if
- there is already a thread bound to this server
-
- Implementation dependent issue: In order to allow the usage of
- application defined schedulers, the given thread must not have the
- scheduling policy SCHED_APP and at the same time be attached to an
- application scheduler different than the frsh scheduler.
-
- [ERR@RETURNED:
- FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
- main scheduler
- 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
- ]
-
-*/
-int
-frsh_bind_thread_to_server
+ * frsh_bind_thread_to_server()
+ *
+ * frsh_bind_thread_to_server: 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.
+ *
+ * It fails if the server's policy is different than FRSH_NONE, or if
+ * there is already a thread bound to this server
+ *
+ * Implementation dependent issue: In order to allow the usage of
+ * application defined schedulers, the given thread must not have the
+ * scheduling policy SCHED_APP and at the same time be attached to an
+ * application scheduler different than the frsh scheduler.
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler
+ * 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
+ * ]
+ **/
+int frsh_bind_thread_to_server
(frsh_server_id_t server,
pthread_t thread);
/**
- This operation unbinds a thread from a server. Since threads with
- no server associated are not allow 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
- are deferred until the critical section is ended
-
- Implementation dependent issue: in the implementation with an
- application scheduler, the thread is still attached to the frsh
- scheduler, but suspended.
-
- [ERR@RETURNED:
- 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
- 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
- ]
-
-*/
-int
-frsh_unbind_thread_from_server (pthread_t thread);
+ * frsh_unbind_thread_from_server()
+ *
+ * This operation unbinds a thread from a server. Since threads with
+ * no server associated are not allow 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
+ * are deferred until the critical section is ended
+ *
+ * Implementation dependent issue: in the implementation with an
+ * application scheduler, the thread is still attached to the frsh
+ * scheduler, but suspended.
+ *
+ * [ERR@RETURNED:
+ * 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
+ * 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
+ * ]
+ **/
+int frsh_unbind_thread_from_server (pthread_t thread);
/**
- This operation stores the Id of the server associated with the
- specified thread in the variable pointed to by server. It returns
- an error if the thread does not exist, it is not under the control
- of the scheduling framework, or is not bound.
-
- [ERR@RETURNED:
- 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
- FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist or the
- server argument is NULL
- ]
-
-*/
-int
-frsh_get_server
+ * frsh_get_server()
+ *
+ * This operation stores the Id of the server associated with the
+ * specified thread in the variable pointed to by server. It returns
+ * an error if the thread does not exist, it is not under the control
+ * of the scheduling framework, or is not bound.
+ *
+ * [ERR@RETURNED:
+ * 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
+ * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist or the
+ * server argument is NULL
+ * ]
+ **/
+int frsh_get_server
(pthread_t thread,
frsh_server_id_t *server);
/**
- 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.
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
- of the server argument is not in range
- 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
- ]
-
-*/
-int
-frsh_get_contract
- (frsh_server_id_t server,
+ * frsh_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.
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
+ * of the server argument is not in range
+ * 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
+ * ]
+ **/
+int frsh_get_contract
+ (frsh_server_id_t server,
frsh_contract_parameters_t *contract);
/**
- The operation eliminates the specified server
- 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.
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the value of server is not in range
- 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
- ]
-
-*/
-int
-frsh_cancel_contract (frsh_server_id_t server);
+ * frsh_cancel_contract()
+ *
+ * The operation eliminates the specified server
+ * 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.
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the value of server is not in range
+ * 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
+ * ]
+ **/
+int frsh_cancel_contract (frsh_server_id_t server);
/**
- The operation renegotiates a contract for an existing server. 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
- contract remains in effect and an error is returned. If it can be
- admitted, it recalculates all necessary parameters for the
- contracts already present in the system anr returns zero. This is a
- potentially blocking operation; it returns when the system has
- either rejected the new contract, or admitted it and made it
- effective.
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL or the
- value of the server argument is not in range
- 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
- FRSH_ERR_REJECTED_CONTRACT : if the renegotiation fails
- ]
-
-*/
-int
-frsh_renegotiate_contract
+ * frsh_renegotiate_contract()
+ *
+ * The operation renegotiates a contract for an existing server. 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
+ * contract remains in effect and an error is returned. If it can be
+ * admitted, it recalculates all necessary parameters for the
+ * contracts already present in the system anr returns zero. This is a
+ * potentially blocking operation; it returns when the system has
+ * either rejected the new contract, or admitted it and made it
+ * effective.
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL or the
+ * value of the server argument is not in range
+ * 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
+ * FRSH_ERR_REJECTED_CONTRACT : if the renegotiation fails
+ * ]
+ **/
+int frsh_renegotiate_contract
(const frsh_contract_parameters_t *new_contract,
frsh_server_id_t server);
/**
- The operation enqueues a renegotiate operation for an existing
- server, 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
- whether the contract can be admitted or not based on the current
- 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.
-
- [ERR@RETURNED:
- 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
- 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
- ]
-
-*/
-int
-frsh_request_contract_renegotiation
+ * frsh_request_contract_renegotiation()
+ *
+ * The operation enqueues a renegotiate operation for an existing
+ * server, 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
+ * whether the contract can be admitted or not based on the current
+ * 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.
+ *
+ * [ERR@RETURNED:
+ * 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
+ * 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
+ * ]
+ **/
+int frsh_request_contract_renegotiation
(const frsh_contract_parameters_t *new_contract,
frsh_server_id_t server,
int sig_notify,
/**
- The operation reports on the status of the last renegotiation
- operation enqueued for the specified server. It is callable even
- after notification of the completion of such operation, if
- requested. If the frsh_request_contract_renegotiation operation has
- not ever been called for the given server the status returned is
- FRSH_NOT_REQUESTED
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
- NULL or the value of the server argument is not in range
- 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
- ]
-
-*/
-int
-frsh_get_renegotiation_status
+ * frsh_get_renegotiation_status()
+ *
+ * The operation reports on the status of the last renegotiation
+ * operation enqueued for the specified server. It is callable even
+ * after notification of the completion of such operation, if
+ * requested. If the frsh_request_contract_renegotiation operation has
+ * not ever been called for the given server the status returned is
+ * FRSH_NOT_REQUESTED
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
+ * NULL or the value of the server argument is not in range
+ * 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
+ * ]
+ **/
+int frsh_get_renegotiation_status
(frsh_server_id_t server,
frsh_renegotiation_status_t *renegotiation_status);
// OBTAINING INFORMATION FROM THE SCHEDULER
////////////////////////////////////////////////////
-
/**
- Returns true if the system is
- configured with the on-line admission test enabled, or false
- otherwise.
-*/
-bool
-frsh_is_admission_test_enabled();
+ * \defgroup getschedinfo Obtaining information from the scheduler
+ *
+ * The following functions are used to obtain available budget and
+ * resource usage in the system. They can be used to adapt the
+ * execution of threads to the load of the system.
+ **/
+/*@{*/
+
/**
- This function stores the current execution time spent by the
- threads bound to the specified server in the variable pointed to by
- cpu_time.
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- cpu_time is NULL
- 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
- ]
+ * frsh_is_admission_test_enabled()
+ *
+ * Returns true if the system is
+ * configured with the on-line admission test enabled, or false
+ * otherwise.
+ **/
+bool frsh_is_admission_test_enabled();
-*/
+/**
+ * This function stores the current execution time spent by the
+ * threads bound to the specified server in the variable pointed to by
+ * cpu_time.
+ *
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
+ * cpu_time is NULL
+ * 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
+ * ]
+ **/
int
frsh_get_resource_usage
(frsh_server_id_t server,
struct timespec *cpu_time);
/**
- This function stores in the variable pointed to by budget the
- remaining execution-time budget associated with the specified
- server
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- budget is NULL
- 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
- ]
+ * This function stores in the variable pointed to by budget the
+ * remaining execution-time budget associated with the specified
+ * server
+
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
+ * budget is NULL
+ * 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
+ * ]
*/
int
/**
- 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
- these pointers is NULL, the corresponding information is not stored.
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
- or budget and period are both NULL
- 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
- ]
+ * 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
+ * these pointers is NULL, the corresponding information is not stored.
+
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
+ * or budget and period are both NULL
+ * 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
+ * ]
*/
int
/////////////////////////////////////////////////////////////////////
/**
- 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.
-
- 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,
- 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
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
- the budget value is greater than the period value
- 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
- ]
+ * 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.
+ *
+ * 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,
+ * 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
+
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
+ * the budget value is greater than the period value
+ * 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
+ * ]
*/
int
bool *accepted);
/**
- this function returns in the variables pointed by budget and
- period, respectively, the current budget and period of the service
- thread.
-
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL
- 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
- ]
+ * this function returns in the variables pointed by budget and
+ * period, respectively, the current budget and period of the service
+ * thread.
+
+ * [ERR@RETURNED:
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL
+ * 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
+ * ]
*/
int
/**
- This operation analizes the schedulability of
- the context that results from negitiating the contracts specified in
- the contracts_up list and cacelling the contracts referenced by the
- servers_down list. If the overall negotiation is successful, a new
- server will be created for each of the elements of the contracts_up
- group, the servers in servers_down will be cancelled, the list of
- new server ids will be returned in the variable pointed to by
- servers_up, and the variable pointed to by accepted will be made
- true. Otherwise, this variable will be made false, and no other
- effect will take place. The function returns the corresponding error
- code if any of the contracts is not correct or any of the server ids
- is not valid.
- Observe that in order to be able to receive the returned arguments,
- the calling thread's server should not be in the servers_down list.
-
- [ERR@RETURNED:
- 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_BAD_ARGUMENT : if any of the servers_up or accepted arguments
- is NULL, if the contracts_up and servers_down arguments are both NULL,
- or any of them has erroneous size or its elements are NULL or not in the
- valid range respectively
- ]
+ * This operation analizes the schedulability of
+ * the context that results from negitiating the contracts specified in
+ * the contracts_up list and cacelling the contracts referenced by the
+ * servers_down list. If the overall negotiation is successful, a new
+ * server will be created for each of the elements of the contracts_up
+ * group, the servers in servers_down will be cancelled, the list of
+ * new server ids will be returned in the variable pointed to by
+ * servers_up, and the variable pointed to by accepted will be made
+ * true. Otherwise, this variable will be made false, and no other
+ * effect will take place. The function returns the corresponding error
+ * code if any of the contracts is not correct or any of the server ids
+ * is not valid.
+ * Observe that in order to be able to receive the returned arguments,
+ * the calling thread's server should not be in the servers_down list.
+
+ * [ERR@RETURNED:
+ * 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_BAD_ARGUMENT : if any of the servers_up or accepted arguments
+ * is NULL, if the contracts_up and servers_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
(const frsh_contracts_group_t *contracts_up,
const frsh_servers_group_t *servers_down,
frsh_servers_group_t *servers_up,
- bool *accepted);
-
-
-//////////////////////////////////////////////////////////////////////
-// INITIALIZATION SERVICES
-//////////////////////////////////////////////////////////////////////
-
-
-/**
- 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.
-
- [ERR@RETURNED:
- FRSH_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already
- been called before
-
- 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();
+ n bool *accepted);
/*@}*/
+/*@}*/ /* From doxygen core module */
+
#endif // _FRSH_CORE_H_
projects / frescor / frsh-include.git / commitdiff