Subversion Repositories shark

Rev

Rev 929 | Rev 985 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed

//fsf_core.h
//=================================================================
//       FFFFFFIII   RRRRR      SSTTTTTTT
//      FF         IIR   RR    SS
//     FF           IR        SS
//    FFFFFF         RRRR    SSSSST
//   FF       FI       RRR  SS
//  FF         II     RRR  SS
// FF           IIIIIR    RS
//
// Basic FSF(FIRST Scheduling Framework) contract management
//================================================================

/**
   \defgroup core Core module

   This module includes the basic functions and services that are
   provided by any FSF implementation. This module includes basic type
   definitions, and functions to

   - create a contract and initialize it
   - set/get the basci 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 fsf_core.h

   This file contains the types, definitions and function prototypes
   for the core module of the First Scheduling Framework.
 */


#include <time.h>
#include <pthread.h>
#include <sys/types.h>
#include "stdbool.h"

#include "fsf_configuration_parameters.h"
#include "fsf_opaque_types.h"
#include "fsf_basic_types.h"

#ifndef _FSF_CORE_H_
#define _FSF_CORE_H_


/////////////////////////////////////////////////////////////////
//      BASIC TYPES AND CONSTANTS are in fsf_basic_types.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 fsf error codes.
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  error is not a valid value
    ]
*/

int fsf_strerror (int error, char *message, size_t size);

/////////////////////////////////////////////////////////////
//                       CONTRACT PARAMETERS
/////////////////////////////////////////////////////////////

/**
   \defgroup contract Contract Creation and Initialization.

   These functions are used to create and initialize a contract, and
   set its 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 FSF_CONTRACT_PARAMETERS_T_OPAQUE fsf_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 (FSF_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 FSF_NONE

    @param     contract the pointer to the contract variable.
    @returns  (PEPPE: should not return anything! change to void??)
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  contract is NULL
    ]
*/

int fsf_initialize_contract (fsf_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

//  sched_policy              => DEFAULT_SCHED_POLICY
//                              (FSF_NONE)


/**
   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
   fsf_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 FSF_BOUNDED,
   FSF_INDETERMINATE or FSF_OVERHEAD)
   
   @returns 0 if the operation is succesful
   @returns FSF_ERR_BAD_ARGUMENT if some of the arguments is not in
            the expected range
    [ERR@RETURNED:
     FSF_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 (FSF_INDETERMINATE, FSF_BOUNDED, or FSF_OVERHEAD)
    ]
*/

int
fsf_set_contract_basic_parameters
  (fsf_contract_parameters_t *contract,
   const struct timespec     *budget_min,
   const struct timespec     *period_max,
   fsf_workload_t            workload);


/**
   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:
     FSF_ERR_BAD_ARGUMENT :  if contract is NULL
    ]
*/

int
fsf_get_contract_basic_parameters
  (const fsf_contract_parameters_t *contract,
   struct timespec  *budget_min,
   struct timespec  *period_max,
   fsf_workload_t   *workload);


/**
   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 FSF_BAD_ARGUMENT if some argument is out of range or not
                 admissible.
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  if contract is NULL or  
       (d_equals_t is true and  deadline is not FSF_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 FSF_NULL_DEADLINE or its value
                                 is grater than the contract´s maximum period)))
    ]

   @see sigexplanation
*/

int
fsf_set_contract_timing_requirements
  (fsf_contract_parameters_t *contract,
   bool                   d_equals_t,
   const struct timespec *deadline,
   int                    budget_overrun_sig_notify,
   union sigval           budget_overrun_sig_value,
   int                    deadline_miss_sig_notify,
   union sigval           deadline_miss_sig_value);

/**
   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:
     FSF_ERR_BAD_ARGUMENT :  if contract is NULL
    ]
   
*/

int
fsf_get_contract_timing_requirements
  (const fsf_contract_parameters_t *contract,
   bool                    *d_equals_t,
   struct timespec         *deadline,
   int                     *budget_overrun_sig_notify,
   union sigval            *budget_overrun_sig_value,
   int                     *deadline_miss_sig_notify,
   union sigval            *deadline_miss_sig_value);

/*@}*/

//////////////////////////////////////////////////////////////////
//                 SYNCHRONIZATION OBJECTS
//////////////////////////////////////////////////////////////////


/**
   \defgroup synch  Synchronization objects
*/

/*@{*/
/**
   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 fsf_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 FSF_SYNCH_OBJ_HANDLE_T_OPAQUE fsf_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     FSF_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
                objects in the system has already exceeded the maximum
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  if synch_handle is 0
     FSF_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization
       objects in the system has already exceeded the maximum
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
    ]

*/

int
fsf_create_synch_obj
    (fsf_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 FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  if synch_handle is 0
     FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_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 fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job
*/

int
fsf_signal_synch_obj
    (fsf_synch_obj_handle_t synch_handle);

/**
   This operation destroys the synchronization object (created by a
   previous call to fsf_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 fsf_create_synch_obj.

   @param synch_handle the handle to the synchronization object
             to be destroyed

   @returns 0 if the operation is succesful
   @returns FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  if synch_handle is 0
     FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
    ]

   @sa fsf_create_synch_obj
*/

int
fsf_destroy_synch_obj
    (fsf_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 FSF_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification
              is in the past.
    [ERR@RETURNED:
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
       under the FSF
     FSF_ERR_NOT_BOUND_THREAD : if the calling thread does not have a valid
       server bound to it
     FSF_ERR_BAD_ARGUMENT :  if abs_time is NULL
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
       is not FSF_BOUNDED
    ]

   @sa fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job

*/

int
fsf_schedule_timed_job
  (const struct timespec *abs_time,
   struct timespec       *next_budget,
   struct timespec       *next_period,
   bool                  *was_deadline_missed,
   bool                  *was_budget_overran);


/**
   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:
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
       under the FSF
     FSF_ERR_NOT_BOUND_THREAD : if the calling thread does not have a valid
       server bound to it
     FSF_ERR_BAD_ARGUMENT :  if the synch_handle given is not valid
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
       is not FSF_BOUNDED
    ]


*/

int
fsf_schedule_triggered_job
  (fsf_synch_obj_handle_t  synch_handle,
   struct timespec         *next_budget,
   struct timespec         *next_period,
   bool                    *was_deadline_missed,
   bool                    *was_budget_overran);


/**
   This call is the same as fsf_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:
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
       under the FSF
     FSF_ERR_NOT_BOUND_THREAD : if the calling thread does not have a valid
       server bound to it
     FSF_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
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the server
       is not FSF_BOUNDED
    ]

*/

int
fsf_timed_schedule_triggered_job
  (fsf_synch_obj_handle_t  synch_handle,
   const struct timespec   *abs_timeout,
   bool                    *timed_out,
   struct timespec         *next_budget,
   struct timespec         *next_period,
   bool                    *was_deadline_missed,
   bool                    *was_budget_overran);




/*@}*/

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

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

typedef int      fsf_server_id_t;             // => 0

/**
    The type references a function that may become a thread's
    code
*/

typedef void * (*fsf_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 fsf scheduler.

    [ERR@RETURNED:
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
       under the FSF
     FSF_ERR_BAD_ARGUMENT :  if the contract or server arguments are NULL
     FSF_ERR_TOO_MANY_SERVERS : if there is no space for more servers
       (the maximum number of them is already reached)
    ]

*/

int
fsf_negotiate_contract
  (const fsf_contract_parameters_t *contract,
   fsf_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 fsf 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
   fsf_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 FSF_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:
     FSF_ERR_BAD_ARGUMENT : if the contract or server arguments are NULL
     FSF_ERR_CONTRACT_REJECTED : if the contract is rejected.
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
       in the contract is FSF_OVERHEAD
     
     It may also return all the errors that may be returned by the
       pthread_create()POSIX function call
    ]

*/

int
fsf_negotiate_contract_for_new_thread
  (const fsf_contract_parameters_t *contract,
   fsf_server_id_t      *server,
   pthread_t            *thread,
   pthread_attr_t       *attr,
   fsf_thread_code_t     thread_code,
   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 FSF_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 fsf 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 fsf scheduler.

    [ERR@RETURNED:
     FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
       an application defined scheduler different than the fsf scheduler
     FSF_ERR_BAD_ARGUMENT :  if the contract or server arguments are NULL
     FSF_ERR_CONTRACT_REJECTED : if the contract is rejected.
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
       in the contract is FSF_OVERHEAD
    ]

*/

int
fsf_negotiate_contract_for_myself
  (const fsf_contract_parameters_t *contract,
   fsf_server_id_t      *server);


/**
   fsf_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 FSF_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 fsf scheduler.

    [ERR@RETURNED:
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
       an application defined scheduler different than the fsf scheduler
     FSF_ERR_BAD_ARGUMENT : if the server value does not complain with the
       expected format or valid range or the given thread does not exist
     FSF_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
       of the server is FSF_OVERHEAD
     FSF_ERR_ALREADY_BOUND : if the given server has a thread already bound
    ]

*/

int
fsf_bind_thread_to_server
  (fsf_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 fsf
   scheduler, but suspended.

    [ERR@RETURNED:
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_BAD_ARGUMENT : if the given thread does not exist
     FSF_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
       under the FSF
     FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
       an application defined scheduler different than the fsf scheduler
     FSF_ERR_NOT_BOUND_THREAD : if the given thread does not have a valid
       server bound to it
    ]

*/

int
fsf_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:
     FSF_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
       under the FSF
     FSF_ERR_NOT_BOUND_THREAD : if the given thread does not have a valid
       server bound to it
     FSF_ERR_BAD_ARGUMENT : if the given thread does not exist or the
       server argument is NULL
    ]

*/

int
fsf_get_server
  (pthread_t       thread,
   fsf_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:
     FSF_ERR_BAD_ARGUMENT :  if the contract argument is NULL or the value
       of the server argument is not in range
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_get_contract
   (fsf_server_id_t server,
    fsf_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:
     FSF_ERR_BAD_ARGUMENT :  if the value of server is not in range
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_cancel_contract (fsf_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:
     FSF_ERR_BAD_ARGUMENT :  if the new_contract argument is NULL or the  
       value of the server argument is not in range
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_renegotiate_contract
  (const fsf_contract_parameters_t *new_contract,
   fsf_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:
     FSF_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
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_request_contract_renegotiation
  (const fsf_contract_parameters_t *new_contract,
   fsf_server_id_t                  server,
   int                              sig_notify,
   union sigval                     sig_value);


/**
   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 fsf_request_contract_renegotiation operation has
   not ever been called for the given server the status returned is
   FSF_NOT_REQUESTED

    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  if the renegotiation_status argument is
       NULL or the value of the server argument is not in range
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_get_renegotiation_status
  (fsf_server_id_t server,
   fsf_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
fsf_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:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
       cpu_time is NULL
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_get_cpu_time
   (fsf_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:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
       budget is NULL
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_get_remaining_budget
   (fsf_server_id_t server,
    struct timespec *budget);


/**
   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:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
       or budget and period are both NULL
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_get_budget_and_period
   (fsf_server_id_t server,
    struct timespec *budget,
    struct timespec *period);



/////////////////////////////////////////////////////////////////////
//           SERVICE THREAD TUNING
/////////////////////////////////////////////////////////////////////

/**
   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
   fsf, 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:
     FSF_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
       the budget value is greater than the period value
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_set_service_thread_data
   (const struct timespec *budget,
    const struct timespec *period,
    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:
     FSF_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread
       has been cancelled or it is not valid
    ]

*/

int
fsf_get_service_thread_data
   (struct timespec *budget,
    struct timespec *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 servers, special background contracts may be created for
//specifying the synchronization requirements.

//The way of specifying a background contract is by setting budget_min
//= period_max = 0. Negotiation may fail if the contract uses
//shared_objects. If the contract has no shared_objects the returned
//server id represents the background and may be used to bind more
//than one thread. If the contract has shared objects a server is
//created to keep track of them, but the associated threads are
//executed in the background, together with the other background
//threads


////////////////////////////////////////////////////////////////////////
//           CHANGE OF MODE: GROUPS OF CONTRACTS
////////////////////////////////////////////////////////////////////////

//Data types

//list of contracts to negotiate
typedef struct {
  int  size;
  fsf_contract_parameters_t*  contracts[FSF_MAX_N_SERVERS];
} fsf_contracts_group_t;

//list of servers to cancel
typedef  struct {
  int             size;
  fsf_server_id_t servers[FSF_MAX_N_SERVERS];
} fsf_servers_group_t;


/**
   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:
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
       under the FSF
     FSF_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
fsf_negotiate_group
   (const fsf_contracts_group_t *contracts_up,
    const fsf_servers_group_t   *severs_down,
    fsf_servers_group_t         *severs_up,
    bool                        *accepted);


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


/**
   We cannot call any fsf functions before fsf_init. After calling
   fsf_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:
     FSF_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
       FSF system start up
    ]

*/

int fsf_init();

/*@}*/


#endif // _FSF_CORE_H_