// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+// Copyright (C) 2006 - 2008 FRESCOR consortium partners:
//
// Universidad de Cantabria, SPAIN
// University of York, UK
// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
-// This file is part of FRSH API
+// This file is part of FRSH (FRescor ScHeduler)
//
-// FRSH API is free software; you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation; either version 2, or (at your option)
-// any later version.
+// FRSH is free software; you can redistribute it and/or modify it
+// under terms of the GNU General Public License as published by the
+// Free Software Foundation; either version 2, or (at your option) any
+// later version. FRSH is distributed in the hope that it will be
+// useful, but WITHOUT ANY WARRANTY; without even the implied warranty
+// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// General Public License for more details. You should have received a
+// copy of the GNU General Public License along with FRSH; see file
+// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
+// Cambridge, MA 02139, USA.
//
-// FRSH API is distributed in the hope that it will be useful, but
-// WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-// General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// distributed with FRSH API; see file COPYING. If not, write to the
-// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
-// 02111-1307, USA.
-//
-// As a special exception, if you include this header file into source
-// files to be compiled, this header file does not by itself cause
-// the resulting executable to be covered by the GNU General Public
-// License. This exception does not however invalidate any other
-// reasons why the executable file might be covered by the GNU General
-// Public License.
+// As a special exception, including FRSH header files in a file,
+// instantiating FRSH generics or templates, or linking other files
+// with FRSH objects to produce an executable application, does not
+// by itself cause the resulting executable application to be covered
+// by the GNU General Public License. This exception does not
+// however invalidate any other reasons why the executable file might be
+// covered by the GNU Public License.
// -----------------------------------------------------------------------
//==============================================
#include "frsh_core_types.h"
#include "frsh_spare_capacity.h"
+
+FRSH_CPP_BEGIN_DECLS
+
/**
* @defgroup core Core module
*
**/
-
/**
* frsh_contract_init()
*
* - period_max => {0,0};
* - budget_max => {0,0};
* - period_min => {0,0};
- * - workload => FRSH_INDETERMINATE
+ * - workload => FRSH_WT_INDETERMINATE
* - d_equals_t => true
* - contract_type => FRSH_CT_REGULAR;
* - deadline => {0,0};
- * - 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};
+ * - budget_overrun_signal => 0; (signal number)
+ * - budget_overrun_siginfo => {0, NULL};
+ * - deadline_miss_signal => 0; (signal number)
+ * - deadline_miss_siginfo => {0, NULL};
*
* - granularity => DEFAULT_GRANULARITY;
* - utilization_set; => size = 0
* @param contract the pointer to the contract object
* @param[in] budget_min the minimum budget for the contract
* @param[in] period_max the maximum period for the contract
- * @param[in] workload the kind of workload (can be FRSH_BOUNDED,
- * FRSH_INDETERMINATE or FRSH_OVERHEAD)
+ * @param[in] workload the kind of workload (can be FRSH_WT_BOUNDED,
+ * FRSH_WT_INDETERMINATE or FRSH_OVERHEAD)
* @param[in] contract_type can be FRSH_CT_REGULAR,
* FRSH_CT_BACKGROUND, FRSH_CT_DUMMY.
*
* @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL
- * or if only one of the timespec values is 0, and also if the
+ * or if only one of the time values is 0, and also if the
* workload or the contract type values are unknown in the
* enumerations.
**/
int frsh_contract_set_basic_params
(frsh_contract_t *contract,
- const struct timespec *budget_min,
- const struct timespec *period_max,
+ const frsh_rel_time_t *budget_min,
+ const frsh_rel_time_t *period_max,
const frsh_workload_t workload,
const frsh_contract_type_t contract_type);
**/
int frsh_contract_get_basic_params
(const frsh_contract_t *contract,
- struct timespec *budget_min,
- struct timespec *period_max,
+ frsh_rel_time_t *budget_min,
+ frsh_rel_time_t *period_max,
frsh_workload_t *workload,
frsh_contract_type_t *contract_type);
* @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,
*
* @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if the contract or the contract_label
- pointer is NULL.
+ * pointer is NULL.
**/
int frsh_contract_get_resource_and_label
(const frsh_contract_t *contract,
* this parameter is ignored (the contract value
* will be NULL_DEADLINE internally). Otherwise, it
* contains the desired deadline value.
- * @param [in] budget_overrun_sig_notify contains the number of the signal
+ * @param [in] budget_overrun_signal contains the number of the signal
* that must be raised if the budget of the vres is overrun.
* If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
* be raised.
- * @param [in] budget_overrun_sig_value contains the value that will be
+ * @param [in] budget_overrun_siginfo contains the value that will be
* passed to the signal "catcher" when the signal is raised.
- * This parameters is not used if the budget_overrun_sig_notify
+ * This parameters is not used if the budget_overrun_signal
* parameter is set to FRSH_NULL_SIGNAL.
- * @param [in] deadline_miss_sig_notify contains the number of the
+ * @param [in] deadline_miss_signal contains the number of the
* signal that must be raised if the deadline of the
* vres is missed. If the value of this parameter is
* FRSH_NULL_SIGNAL, no signal is raised.
- * @param [in] deadline_miss_sig_value contains the value that will be
+ * @param [in] deadline_miss_siginfo contains the value that will be
* passed to the signal "catcher" when the signal is
* raised. This parameter is not used if the
- * deadline_sig_notify parameter is set to NULL_SIGNAL
+ * deadline_signal parameter is set to NULL_SIGNAL
*
* @return 0 if successful\n
* FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n
* (d_equals_t is true and deadline is not FRSH_NULL_DEADLINE) \b or \n
- * (budget_overrun_sig_notify is not a valid signal) \b or \n
- * (deadline_miss_sig_notify is not a valid signal) \b or \n
+ * (budget_overrun_signal is not a valid signal) \b or \n
+ * (deadline_miss_signal is not a valid signal) \b or \n
* (d_equals_t is false but (deadline is FRSH_NULL_DEADLINE or its value
* is grater than the contract's maximum period))
*
int frsh_contract_set_timing_reqs
(frsh_contract_t *contract,
const bool d_equals_t,
- const struct timespec *deadline,
+ const frsh_rel_time_t *deadline,
const frsh_signal_t budget_overrun_signal,
const frsh_signal_info_t budget_overrun_siginfo,
const frsh_signal_t deadline_miss_signal,
int frsh_contract_get_timing_reqs
(const frsh_contract_t *contract,
bool *d_equals_t,
- struct timespec *deadline,
+ frsh_rel_time_t *deadline,
frsh_signal_t *budget_overrun_signal,
frsh_signal_info_t *budget_overrun_siginfo,
frsh_signal_t *deadline_miss_signal,
* 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
+ * @param[out] synch_handle pointer to the variable that will contain
+ * the handle to the newly created synchronization object
+ *
+ * @return 0 if the operation is succesful
+ * FRSH_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
+ * objects in the system has already exceeded the maximum
*
- * @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_synchobj_destroy()
*
* This operation destroys the synchronization object (created by a
- * previous call to frsh_create_synch_obj) that is referenced by the
+ * previous call to frsh_synchobj_create) that is referenced by the
* synch_handle variable. After calling this operation, the
* synch_handle variable can not be used until it is initialized again
- * by a call to frsh_create_synch_obj.
+ * by a call to frsh_synchobj_create.
*
* @param synch_handle the handle to the synchronization object
* to be destroyed
**/
int frsh_synchobj_wait
(const frsh_synchobj_handle_t synch_handle,
- struct timespec *next_budget,
- struct timespec *next_period,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
bool *was_deadline_missed,
bool *was_budget_overran);
/**
* frsh_synchobj_wait_with_timeout()
*
-g * This call is the same as frsh_synchobj_wait() but with an extra
+ * This call is the same as frsh_synchobj_wait() but with an extra
* absolute timeout. The timed_out argument, indicates whether the
* function returned because of the expiration of the timeout or not.
*
**/
int frsh_synchobj_wait_with_timeout
(const frsh_synchobj_handle_t synch_handle,
- const struct timespec *abs_timeout,
+ const frsh_abs_time_t *abs_timeout,
bool *timed_out,
- struct timespec *next_budget,
- struct timespec *next_period,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
bool *was_deadline_missed,
bool *was_budget_overran);
* mentioned abobe, only when the call finishes the budget may be
* replenished.
*
- * * @param [in] abs_time absolute time at which the budget will be
+ * @param [in] abs_time absolute time at which the budget will be
* replenished
*
* @param [out] next_budget upon return of this function, the variable
* @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
**/
int frsh_timed_wait
- (const struct timespec *abs_time,
- struct timespec *next_budget,
- struct timespec *next_period,
+ (const frsh_abs_time_t *abs_time,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
bool *was_deadline_missed,
bool *was_budget_overran);
+
+/**
+ * frsh_vresperiod_wait()
+ *
+ * Suspend the calling thread until the start of the specified virtual
+ * resource period, for a synchronized workload.
+ *
+ * Virtual resource periods are numbered. The number of the current
+ * period can be obtained through the frsh_vres_get_period_number()
+ * operation.
+ **/
+int frsh_vresperiod_wait
+ (const frsh_vres_id_t vres,
+ long period_num);
+
+
+/**
+ * frsh_vres_get_period()
+ *
+ * Return the current period number, for a virtual resource of
+ * synchronized workload.
+ **/
+int frsh_vres_get_period_number
+ (const frsh_vres_id_t vres,
+ long *period_num);
+
+
+
+
/*@}*/
///////////////////////////////////////////////////////////////////
int frsh_thread_get_vres_id(const frsh_thread_id_t thread,
frsh_vres_id_t *vres_id);
+/**
+ * frsh_vres_get_priority()
+ *
+ * This operation stores the priority currently associated
+ * with the specified vres in the variable pointed to by
+ * priority. It returns an error if the vres_id is not recognised.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
+ * of the vres argument is not in range \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * scheduled under FRSH \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES: if the vres of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+int frsh_vres_get_priority
+ (frsh_vres_id_t vres_id,
+ int *priority);
+
/**
* frsh_vres_get_contract()
*
*
* If the vres is not and has not been involved in any of the
* frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
- * operations, the status returned is FRSH_NOT_REQUESTED
+ * operations, the status returned is FRSH_RS_NOT_REQUESTED
*
* @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
/**
* frsh_group_change_mode_sync()
*
- * An extension of frsh_negotiate_group() by adding the possibility of
+ * An extension of frsh_group_negotiate() by adding the possibility of
* specifying also group contract renegotiation and removal.
*
* NOTE: This function will be implemented in a second phase after
* as it is practical.
*
* NOTE: This function will be implemented in a second phase after
- * having fully implemented frsh_negotiate_group() in order to
+ * having fully implemented frsh_group_negotiate() in order to
* better grasp possible issues that the problem may raise.
*
* This is a draft of the specification, it is yet subject to
**/
int frsh_vres_get_usage
(const frsh_vres_id_t vres,
- struct timespec *spent);
+ frsh_rel_time_t *spent);
+
+
+/**
+ * frsh_vres_get_job_usage()
+ *
+ * Get the execution time of the current job of the specified virtual
+ * resource for a bounded or synchronized workload.
+ **/
+int frsh_vres_get_job_usage
+ (const frsh_vres_id_t vres,
+ frsh_rel_time_t *spent);
+
/**
* frsh_vres_get_remaining_budget()
**/
int frsh_vres_get_remaining_budget
(const frsh_vres_id_t vres,
- struct timespec *budget);
+ frsh_rel_time_t *budget);
/**
**/
int frsh_vres_get_budget_and_period
(const frsh_vres_id_t vres,
- struct timespec *budget,
- struct timespec *period);
+ frsh_rel_time_t *budget,
+ frsh_rel_time_t *period);
/*@}*/
* has been cancelled or it is not valid
*
**/
-int frsh_service_thread_set_data (const struct timespec *budget,
- const struct timespec *period,
+int frsh_service_thread_set_data (const frsh_rel_time_t *budget,
+ const frsh_rel_time_t *period,
bool *accepted);
/**
*
**/
int frsh_service_thread_get_data
- (struct timespec *budget,
- struct timespec *period);
+ (frsh_rel_time_t *budget,
+ frsh_rel_time_t *period);
/*@}*/
//threads
-
-
+FRSH_CPP_END_DECLS
#endif // _FRSH_CORE_H_
projects / frescor / frsh-include.git / blobdiff