Update transaction API

[frescor/frsh-include.git] / frsh_core.h

// -----------------------------------------------------------------------
//  Copyright (C) 2006 - 2009 FRESCOR consortium partners:
//
//    Universidad de Cantabria,              SPAIN
//    University of York,                    UK
//    Scuola Superiore Sant'Anna,            ITALY
//    Kaiserslautern University,             GERMANY
//    Univ. Politécnica  Valencia,           SPAIN
//    Czech Technical University in Prague,  CZECH REPUBLIC
//    ENEA                                   SWEDEN
//    Thales Communication S.A.              FRANCE
//    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
//        in part by the European Union Sixth Framework Programme
//        The European Union is not liable of any use that may be
//        made of this code.
//
//
//  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
//                       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 (FRescor ScHeduler)
//
//  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.
//
//  As a special exception, including FRSH header files in a file,
//  instantiating FRSH generics or templates, or linking other files
//  with FRSH objects to produce an executable application, does not
//  by itself cause the resulting executable application to be covered
//  by the GNU General Public License. This exception does not
//  however invalidate any other reasons why the executable file might be
//  covered by the GNU Public License.
// -----------------------------------------------------------------------

//==============================================
//  ******** *******    ********  **      **
//  **///// /**////**  **//////  /**     /**
//  **      /**   /** /**        /**     /**
//  ******* /*******  /********* /**********
//  **////  /**///**  ////////** /**//////**
//  **      /**  //**        /** /**     /**
//  **      /**   //** ********  /**     /**
//  //       //     // ////////   //      //
//
// FRSH(FRescor ScHeduler), pronounced "fresh"
//==============================================

#ifndef _FRSH_CORE_H_
#define _FRSH_CORE_H_


/**
 * @file frsh_core.h
 **/


#include <time.h>
#include <sys/types.h>

#include "frsh_core_types.h"
#include "frsh_spare_capacity.h"


FRSH_CPP_BEGIN_DECLS

/**
 * @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 vres id
 * - create and bind threads to vres
 * - create/destroy a synchronization object
 * - manage bounded workloads
 *
 **/


//////////////////////////////////////////////////////////////////////
//           INITIALIZATION SERVICES
//////////////////////////////////////////////////////////////////////

/**
 * @defgroup initialization Initialization services
 * @ingroup core
 *
 * 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 and create new threads if needed.  The
 * second time this function is called it fails.
 *
 * @return 0 if no error. \n
 *  FRSH_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already
 *                                        been called before\n
 *  .
 *  It may also return any of the errors that may be returned by the
 *  underlying operating system primitives required to perform the
 *  FRSH system start up
 *
 **/
int frsh_init();

/**
 * frsh_destroy()
 *
 * Reverts the efect of frsh_init().
 */
void frsh_destroy();

/*@}*/


/////////////////////////////////////////////////////////////
//                       CONTRACT PARAMETERS
/////////////////////////////////////////////////////////////
/**
 * @defgroup contract Contract Creation and Initialization.
 * @ingroup core
 *
 * These functions are used to create and initialize a contract, and
 * set its parameters.
 *
 * @{
 **/


/**
 * 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_label               => ""
 * - budget_min                => {0,0};
 * - period_max                => {0,0};
 * - budget_max                => {0,0};
 * - period_min                => {0,0};
 * - workload                  => FRSH_WT_INDETERMINATE
 * - d_equals_t                => true
 * - contract_type             => FRSH_CT_REGULAR;
 * - deadline                  => {0,0};
 * - budget_overrun_signal => 0;  (signal number)
 * - budget_overrun_siginfo  => {0, NULL};
 * - deadline_miss_signal  => 0;  (signal number)
 * - deadline_miss_siginfo   => {0, NULL};
 *
 * - granularity               => DEFAULT_GRANULARITY;
 * - utilization_set;          => size = 0
 * - 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.
 *
 * @return 0 if no error \n
 *     FRSH_ERR_BAD_ARGUMENT :  contract is NULL
 *
 **/
int frsh_contract_init(frsh_contract_t *contract);


/**
 * frsh_contract_destroy()
 *
 * The operation deallocates all memory which might be allocated for
 * the contract.
 *
 * @param contract the pointer to the contract variable.
 **/
void frsh_contract_destroy(frsh_contract_t *contract);


/**
 * frsh_contract_set_basic_params()
 *
 * The operation updates the specified contract parameters object by
 * 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_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_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 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 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);

/**
 * frsh_contract_get_basic_params()
 *
 * 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] period_max pointer to preallocated space
 * @param[out] workload pointer to preallocated space
 * @param[out] contract_type pointer to preallocated space
 *
 * @return   0 if no error \n
 *       FRSH_ERR_BAD_ARGUMENT :  if one of the contract or
 *                                    pointers is NULL.
 *
 **/
int frsh_contract_get_basic_params
  (const frsh_contract_t *contract,
   frsh_rel_time_t  *budget_min,
   frsh_rel_time_t  *period_max,
   frsh_workload_t   *workload,
   frsh_contract_type_t *contract_type);

/**
 * frsh_contract_set_resource_and_label()
 *
 * Specify 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_contract_set_timing_reqs()
 *
 * 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
 *                        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 is ignored (the contract value
 *                       will be NULL_DEADLINE internally). Otherwise, it
 *                       contains the desired deadline value.
 *
 * @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_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 frsh_rel_time_t        *deadline);

/**
 * frsh_contract_get_timing_reqs()
 *
 * The operation obtains the corresponding input parameters from the
 * specified contract object. If d_equals_t is true, the deadline will
 * be set to FRSH_NULL_DEADLINE.
 *
 * @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,
   frsh_rel_time_t         *deadline);


/*@}*/

//////////////////////////////////////////////////////////////////
//                 SYNCHRONIZATION OBJECTS
//////////////////////////////////////////////////////////////////
/**
 * @defgroup synch  Synchronization objects
 * @ingroup core
 *
 * 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 vres (bounded-workload or indeterminate-workload)
 * wakes them up with a signal call the earliest at the beginning of
 * the next period.
 *
 * Indeterminate-workload vres cannot queue themselves here because
 * they don't have any budget to return.  However they can signal on
 * the objects to activate a waiting workload vres.
 *
 * For classical signal/wait synchronisation paradigms the application
 * must use whatever mechanism the underlying OS provides.
 *
 * 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.
 *
 * @{
 **/


/**
 * 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]  synch_handle pointer to the variable that will contain
 *                  the handle to the newly created synchronization object
 *
 * @return      0 if the operation is succesful
 *              FRSH_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
 *              objects in the system has already exceeded the maximum
 *
 *   FRSH_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization
 *      objects in the system has already exceeded the maximum\n
 *   .
 *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 *      scheduled under FRSH\n
 *   .
 *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 *
 **/
int frsh_synchobj_create
    (frsh_synchobj_handle_t *synch_handle);


/**
 * frsh_synchobj_destroy()
 *
 * This operation destroys the synchronization object (created by a
 * previous call to frsh_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_synchobj_create.
 *
 * @param synch_handle the handle to the synchronization object
 *            to be destroyed
 *
 * @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 FRSH \n
 *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 *                            running
 *
 * @sa frsh_synchobj_create
 **/
int frsh_synchobj_destroy
    (const frsh_synchobj_handle_t synchobj_handle);

/**
 * frsh_synchobj_wait()
 *
 * This operation is invoked by threads associated with bounded
 * workload vres to indicate that a job has been completed (and
 * that the scheduler may reassign the unused capacity of the current
 * job to other vres).
 *
 * 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.
 *
 * This function can also be called to schedule the first job of a
 * recently created vres and make it start when a signal operation
 * has been sent from another thread.
 *
 * 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 vres won't have to wait for another
 * one.
 *
 * 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 vres has a positive budget and the
 * scheduler schedules the calling thread again, the call returns and
 * the vres continues executing.
 *
 * 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, 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 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 vres
 *                       will be waiting.
 * @param next_budget[out]  Upon return of this function, the variable
 *                          pointed by this function will be equal to
 *                                      the current vres budget. If this parameter is
 *                                      set to NULL, no action is taken
 * @param next_period[out]  The vres period upon return (ignored if NULL).
 * @param was_deadline_missed Upon return whether the deadline was
 *                           missed in the previous period.
 * @param was_budget_overran
 *
 *
 * @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 \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 vres was waiting on it. \n
 *   FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
 *     is not FRSH_BOUNDED
 *
 **/
int frsh_synchobj_wait
  (const frsh_synchobj_handle_t  synch_handle,
   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()
 *
 * 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.
 *
 * @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 \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_synchobj_wait_with_timeout
  (const frsh_synchobj_handle_t  synch_handle,
   const frsh_abs_time_t         *abs_timeout,
   bool                          *timed_out,
   frsh_rel_time_t               *next_budget,
   frsh_rel_time_t               *next_period,
   bool                          *was_deadline_missed,
   bool                          *was_budget_overran);

/**
 * frsh_synchobj_signal()
 *
 * This function sends a notification event to the synchronization object
 * 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
 *                 notify.
 *
 * @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 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_synchobj_wait, frsh_synchobj_wait_with_timeout
 **/
int frsh_synchobj_signal
    (const frsh_synchobj_handle_t synch_handle);

/**
 * frsh_timed_wait()
 *
 * This operation is invoked by threads associated with bounded
 * workload vres to indicate that a job has been completed (and
 * that the scheduler may reassign the unused capacity of the current
 * job to other vres). It is also invoked when the first job of
 * such threads has to be scheduled.
 *
 * 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
 * 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
 * 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 vres 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 vres budget. If this parameter is
 *                          set to NULL, no action is taken.
 *
 * @param [out] next_period upon return of this function, the variable
 *                          pointed by this function will be equal to
 *                          the current vres period. If this parameter is
 *                          set to NULL, no action is taken.
 *
 * @param [out] was_deadline_missed upon return of this function, the
 *                          variable pointed by this function will be
 *                          equal to true if the previous vres deadline
 *                          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 vres budget was
 *                          overrun, to false otherwise. If this
 *                          parameter is set to NULL, no action is
 *                          taken.
 *
 * @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_synchobj_wait, frsh_synchobj_wait_with_timeout
 **/
int frsh_timed_wait
  (const frsh_abs_time_t *abs_time,
   frsh_rel_time_t       *next_budget,
   frsh_rel_time_t       *next_period,
   bool                  *was_deadline_missed,
   bool                  *was_budget_overran);



/**
 * frsh_vresperiod_wait()
 *
 * Suspend the calling thread until the start of the specified virtual
 * resource period of a vres_id, for a synchronized workload.
 *
 * Virtual resource periods are numbered. The number of the current
 * period can be obtained through the frsh_vres_get_period_number()
 * operation.
 **/
int frsh_vresperiod_wait(unsigned long period_num,
                         frsh_rel_time_t       *next_budget,
                         frsh_rel_time_t       *next_period,
                         bool                  *was_deadline_missed,
                         bool                  *was_budget_overran);


/**
 * frsh_vres_get_period()
 *
 * Return the current period number, for a virtual resource of
 * synchronized workload.
 **/
int frsh_vres_get_period_number
   (const frsh_vres_id_t vres,
    long *period_num);




/*@}*/

///////////////////////////////////////////////////////////////////
//                 CONTRACT NEGOCIATION OPERATIONS
///////////////////////////////////////////////////////////////////

/**
 * @defgroup negotiate Negotiate contract functions
 * @ingroup core
 *
 * 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 vres please refer to the
 * hierarchical module.
 *
 * @{
 **/



/**
 * frsh_contract_negotiate()
 *
 * The operation negotiates a contract and if accepted it will return
 * 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 vres 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. 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 \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_contract_negotiate
  (const frsh_contract_t *contract,
   frsh_vres_id_t        *vres);

/**
 * frsh_thread_create_and_bind()
 *
 * 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 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 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 \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
 *     fosa_thread_create() function call
 *
 **/
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_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 vres.
 *
 * This method is suggested as a way to initate components and
 * plugins.  The event that triggers the component activation should
 * arrive to an application thread that could use this function to
 * create a thread used in its initialisation.
 *
 * The attribute parameter is overwritten as necessary to introduce
 * the adequate scheduling policy and priority.
 *
 * @param[in]  thread_code   Function to be executed by the new
 *                           thread.
 * @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_label   Contract label for the new vres.
 * @param[out] thread_id     Id of the new thread.
 * @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_thread_create_in_background
    (frsh_thread_code_t thread_code,
     const void *thread_arg,
     const char *contract_label,
     frsh_thread_attr_t *attr,
     frsh_thread_id_t *thread_id,
     frsh_vres_id_t *vres_id);



/**
 * frsh_thread_join_in_background()
 *
 * This function is aimed for external threads to join FRSH in the
 * least disturbing possible mode.
 *
 * Upon calling this function by a thread which has been created
 * natively in the OS, it joins the framework and gets inmediately
 * bound to an on-the-fly generated background contract.
 *
 * In order to gain a higher priority then it can renegotiate a
 * contract for its vres with the needed parameters.
 *
 * @param[in] resource_id:   Resource (CPU) in which the vres will
 *                           be associated.
 *
 * @param[in] resource_type: Resource type (should be CPU) for the
 *                           contract.
 *
 * @param[in] label:         Label to be added to the contract.
 *
 * @param[out] vres_id:      Resulting vres_id from the on-the-fly
 *                           generated background contract.
 *
 * @return  0 if successful\n
 *          FRSH_ERR_NOT_CONTRACTED_VRES if the thread is already
 *          bound to a vres.
 **/
int frsh_thread_join_in_background(frsh_resource_id_t resource_id,
                                   frsh_resource_type_t resource_type,
                                   const char *label,
                                   frsh_vres_id_t *vres_id);



/**
 * frsh_thread_bind()
 *
 * 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 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
 * 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.
 *
 * @return 0 if successful \n
 *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 *     main scheduler \n
 *   FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 *     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_thread_bind
  (const frsh_vres_id_t   vres,
   const frsh_thread_id_t thread);


/**
 * frsh_thread_unbind()
 *
 * 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
 * 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.
 *
 * @return 0 if successful \n
 *   FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
 *     main scheduler \n
 *   FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist \n
 *   FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
 *     under FRSH \n
 *   FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
 *     an application defined scheduler different than the frsh
 *     scheduler \n
 *   FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
 *     vres bound to it
 **/
int frsh_thread_unbind(const frsh_thread_id_t thread);

/**
 * frsh_vres_set_notification()
 *
 * This function setups notification signals for CPU vres. It is
 * necessary to call this function before bounding the thread to the
 * vres.
 * 
 * @param [in] budget_overrun_signal contains the number of the signal
 *                that must be raised if the budget of the vres is
 *                overrun by the thread.
 *                If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
 *                be raised.
 * @param [in] budget_overrun_siginfo contains the value that will be
 *               passed to the signal "catcher" when the signal is raised.
 *               This parameters is not used if the budget_overrun_signal
 *               parameter is set to FRSH_NULL_SIGNAL.
 * @param [in] deadline_miss_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_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_signal parameter is set to NULL_SIGNAL
 **/
int frsh_vres_set_notification(
        frsh_vres_id_t vres,
        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_thread_get_vres_id()
 *
 * 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 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
 *     vres argument is NULL
 *
 **/
int frsh_thread_get_vres_id(const frsh_thread_id_t       thread,
                    frsh_vres_id_t *vres_id);

/**
 * frsh_vres_get_priority()
 *
 * This operation stores the priority currently associated
 * with the specified vres in the variable pointed to by
 * priority. It returns an error if the vres_id is not recognised.
 *
 * @return 0 if no error \n
 *   FRSH_ERR_BAD_ARGUMENT :  if the contract argument is NULL or the value
 *     of the vres argument is not in range \n
 *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 *     scheduled under FRSH \n
 *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 *        running \n
 *   FRSH_ERR_NOT_CONTRACTED_VRES: if the vres of the calling thread
 *     has been cancelled or it is not valid
 *
 **/
int frsh_vres_get_priority
     (frsh_vres_id_t            vres_id,
      int *priority);

/**
 * frsh_vres_get_contract()
 *
 * This operation stores the contract parameters currently associated
 * 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 \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_contract
  (const frsh_vres_id_t vres,
    frsh_contract_t *contract);

/**
 * 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.
 *
 * 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 \n
 *   FRSH_ERR_BAD_ARGUMENT :  if the contract argument is NULL or the
 *     contract_label is NULL \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_CONTRACT_LABEL_UNKNOWN: if the contract_label is not known
 **/
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_contract_cancel()
 *
 * 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 vres.
 *
 * @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 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_contract_cancel (const frsh_vres_id_t vres);


/**
 * frsh_contract_renegotiate_sync()
 *
 * 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
 * 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 and 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.
 *
 *  @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 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_CONTRACT_REJECTED : if the renegotiation fails
 *
 **/
int frsh_contract_renegotiate_sync
  (const frsh_contract_t *new_contract,
   const frsh_vres_id_t vres);


/**
 * frsh_contract_renegotiate_async()
 *
 * The operation enqueues a renegotiate operation for an existing
 * 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
 * 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
 * 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.
 * @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 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_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_vres_get_renegotiation_status()
 *
 * The operation reports on the status of the last renegotiation
 * operation enqueued for the specified vres. It is callable even
 * after notification of the completion of such operation, if
 * requested.
 *
 * 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_RS_NOT_REQUESTED
 *
 * @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 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_renegotiation_status
  (const frsh_vres_id_t vres,
   frsh_renegotiation_status_t *renegotiation_status);

/*@}*/

////////////////////////////////////////////////////////////////////////
//           CHANGE OF MODE: GROUPS OF CONTRACTS
////////////////////////////////////////////////////////////////////////
/**
 * @defgroup groupofcontracts Group of contracts
 * @ingroup core
 *
 * 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 and atomically.
 *
 * @{
 **/

/**
 * frsh_group_change_mode_sync()
 *
 * This function performs a set of negotiation operations which can
 * include: adding new contracts (neg), modifying existing vres (reneg)
 * or cancelling existing vres (cancel).
 *
 * If one of the group operations has a NULL value, unless it causes an
 * inconsistency the system will suppose that no operation of that
 * type (neg, reneg or cancel) should be done.
 *
 * The virtual resources resulting from negotiations of new contracts are
 * returned in the parameter 'new_vres' which must be provided by the user.
 *
 * If the on-line admission test is enabled, FRSH analizes the
 * schedulability of the context that would  result in the new
 * contract situation with removed, changed and added contracts.
 *
 * A successful return code will mean that all contracts have been
 * accepted  and all required operations (creation, cancellation or
 * update of vres) have been carried out to reach the new running
 * context.
 *
 * If any of the contracts is not accepted a corresponding error shall be
 * returned and no changes will be made to the previously running context.
 *
 * This call is a synchronous, potentially blocking operation.  It
 * returns when the system has rejected the contracts or accepted
 * and made them effective.
 *
 * @param[in] contracts_to_neg    List of new contracts to negotiate
 * @param[in] contracts_to_reneg  List of contracts to renegotiate
 * @param[in] vres_to_reneg       List of vres to renegotiate
 * @param[in] vres_to_cancel      List of vres to cancel
 * @param[out] new_vres           List of vres of new contracts.
 *
 * @return 0 if no error \n
 *    FRSH_ERR_BAD_ARGUMENT Invalid pointer or group identifier. \n
 *    FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
 *    FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
 *       is not recognised. \n
 *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
 *       is not scheduled under FRSH. \n
 *    FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
 *       not running. \n
 *    FRSH_ERR_INTERNAL_ERROR:  Erroneous binding or malfunction of
 *       FRSH main scheduler. \n
 *    FRSH_ERR_REJECTED_CONTRACT:  The negotiation of one of the
 *       proposed contracts has failed.
 **/
int frsh_group_change_mode_sync
                            (const frsh_contracts_group_t *contracts_to_neg,
                             const frsh_contracts_group_t *contracts_to_reneg,
                             const frsh_vres_group_t      *vres_to_reneg,
                             const frsh_vres_group_t      *vres_to_cancel,
                             frsh_vres_group_t            *new_vres);

/**
 * frsh_group_change_mode_async()
 *
 * This is an asynchronous (non-blocking) version of the previous function,
 * frsh_group_change_mode_sync() and thus, it returns inmediately.
 *
 * The status of the change of mode and the identifiers for new virtual
 * resources must be requested with the function 'frsh_group_get_status'
 * by using the return parameter 'group'.
 *
 * As in the asynchronous renegotiations, when the operation is completed,
 * the user is notified with a signal so he can check the final result with
 * 'frsh_group_get_status'. In case that FRSH_NULL_SIGNAL is used, no
 * signal will be sent to the user.
 *
 * @param[in] contracts_to_neg    List of new contracts to negotiate
 * @param[in] contracts_to_reneg  List of contracts to renegotiate
 * @param[in] vres_to_reneg       List of vres to renegotiate
 * @param[in] vres_to_cancel      List of vres to cancel
 * @param[in] signal              Signal number to notify completion of
 *                                the change of mode. If FRSH_NULL_SIGNAL,
 *                                no signal will be raised.
 * @param[in] signal_info         Data associated to the signal
 * @param[out] group              The group identifier to get the status
 *
 * @return 0 if no error \n
 *    FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n
 *    FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
 *    FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
 *       is not recognised. \n
 *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
 *       is not scheduled under FRSH. \n
 *    FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
 *       not running. \n
 *    FRSH_ERR_INTERNAL_ERROR:  Erroneous binding or malfunction of
 *       FRSH main scheduler.
 **/
int frsh_group_change_mode_async
                            (const frsh_contracts_group_t *contracts_to_neg,
                             const frsh_contracts_group_t *contracts_to_reneg,
                             const frsh_vres_group_t      *vres_to_reneg,
                             const frsh_vres_group_t      *vres_to_cancel,
                             const frsh_signal_t          signal,
                             const frsh_signal_info_t     signal_info,
                             frsh_group_id_t              *group);

/**
 * frsh_group_get_status()
 *
 * This function is similar to 'frsh_vres_get_renegotiation_status' but it
 * is intented for group negotiations (changes of mode).
 *
 * The operation reports on the status of the last negotiation
 * operation enqueued for the specified group identifier.
 *
 * The status value can be one of the following values:
 *
 *    - FRSH_RS_IN_PROGRESS: the change of mode is in progress
 *    - FRSH_RS_REJECTED: the change of mode was not accepted
 *    - FRSH_RS_ADMITTED: the change of mode was accepted
 *    - FRSH_RS_NOT_REQUESTED: no change of mode has been requested yet
 *
 * When status returns 'FRSH_RS_ADMITTED', the array 'new_vres' contains
 * the values for the new virtual resources (if there was any).
 *
 * This function frees the group identifier when status returns something
 * different than FRSH_RS_IN_PROGRESS so further calls to this function may
 * return inconsistent values.
 *
 * @param[in]  group     The group identifier
 * @param[out] status    The status of the change of mode
 * @param[out] new_vres  List of vres for the negotiation of new contracts.
 *
 * @return 0 if no error \n
 *    FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n
 *    FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
 *    FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
 *       is not recognised. \n
 *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
 *       is not scheduled under FRSH. \n
 *    FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
 *       not running. \n
 *    FRSH_ERR_INTERNAL_ERROR:  Erroneous binding or malfunction of
 *       FRSH main scheduler.
 **/
int frsh_group_get_status(const frsh_group_id_t       group,
                          frsh_renegotiation_status_t *status,
                          frsh_vres_group_t           *new_vres);


/*@}*/


////////////////////////////////////////////////////
//           OBTAINING INFORMATION FROM THE SCHEDULER
////////////////////////////////////////////////////

/**
 * @defgroup getschedinfo Obtaining information from the scheduler
 *
 * @ingroup core
 *
 * 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 according to the load of the system.
 *
 * @{
 **/


/**
 * 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_config_is_admission_test_enabled();

/**
 * frsh_vres_get_usage()
 *
 * This function stores the current execution time spent by the
 * threads bound to the specified vres in the variable pointed to by
 * cpu_time.
 *
 * @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 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_vres_get_usage
   (const frsh_vres_id_t vres,
    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()
 *
 * This function stores in the variable pointed to by budget the
 * remaining execution-time budget associated with the specified
 * vres.
 *
 *  @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 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_remaining_budget
   (const frsh_vres_id_t vres,
    frsh_rel_time_t *budget);


/**
 * 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 vres. If any of
 * these pointers is NULL, the corresponding information is not stored.
 *
 * @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 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_budget_and_period
   (const frsh_vres_id_t vres,
    frsh_rel_time_t *budget,
    frsh_rel_time_t *period);

/*@}*/

/////////////////////////////////////////////////////////////////////
//           SERVICE THREAD TUNING
/////////////////////////////////////////////////////////////////////
/**
 * @defgroup servthtuning Service thread tuning
 *
 * @ingroup core
 *
 * 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.
 *
 * @{
 **/

/**
 * frsh_service_thread_set_data()
 *
 * 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 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 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 \n
 *   FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
 *     the budget value is greater than the period value \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_service_thread_set_data (const frsh_rel_time_t *budget,
                                  const frsh_rel_time_t *period,
                                  bool                  *accepted);

/**
 * 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 \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 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_service_thread_get_data
   (frsh_rel_time_t *budget,
    frsh_rel_time_t *period);


/*@}*/


////////////////////////////////////////////////////////////////////////
//           BACKGROUND MANAGEMENT
////////////////////////////////////////////////////////////////////////

//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 vres.  Special background contracts may be created for
//specifying the synchronization requirements.

//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
//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


////////////////////////////////////////////////////////////////////////
//           OTHER
////////////////////////////////////////////////////////////////////////

/**
 * Returns resource id of local CPU.
 *
 * The ID is determined from environment variable FRSH_CPU_ID or, if
 * that is not defined, the compile time default (defined in
 * config.target/omk).
 */
frsh_resource_id_t frsh_get_local_cpu_id(void);

FRSH_CPP_END_DECLS

#endif // _FRSH_CORE_H_