Subversion Repositories shark

Compare Revisions

Ignore whitespace Rev 982 → Rev 983

/shark/trunk/ports/first/fsf_include/fsf_core.h
1,3 → 1,11
/**
@file This file contains the functions and definitions for the core
module.
 
The file contains all fuinctions and data structures for the core
module of the FSF.
*/
 
//fsf_core.h
//=================================================================
// FFFFFFIII RRRRR SSTTTTTTT
11,33 → 19,11
// 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 <stdbool.h>
 
#include "fsf_configuration_parameters.h"
#include "fsf_opaque_types.h"
47,12 → 33,36
#define _FSF_CORE_H_
 
 
/////////////////////////////////////////////////////////////////
// BASIC TYPES AND CONSTANTS are in fsf_basic_types.h
/////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////
// INITIALIZATION SERVICES
//////////////////////////////////////////////////////////////////////
 
/**
\ingroup coremodule
 
\defgroup core_init Initialization and utilities
 
@{
*/
 
/**
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.
 
@retval 0 if the system is initialized
@retval FSF_ERR_SYSTEM_ALREADY_INITIALIZED if the function has already
been called before
@retval others 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();
 
/**
This function converts an error code to an error message that is
stored in the buffer starting at the location pointed to by
62,18 → 72,20
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
]
 
@retval 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.
\ingroup coremodule
\defgroup core_contract Contract Creation and Initialization.
 
These functions are used to create and initialize a contract, and
set its parameters.
91,21 → 103,17
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
- 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;
- 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
]
@retval FSF_ERR_BAD_ARGUMENT contract is NULL
*/
int fsf_initialize_contract (fsf_contract_parameters_t *contract);
 
142,20 → 150,16
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 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)
@param [in] workload the kind of workload (can be FSF_BOUNDED or
FSF_INDETERMINATE)
@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
@retval 0 if the operation is succesful
@retval 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)
]
is not a proper value (FSF_INDETERMINATE or FSF_BOUNDED)
*/
int
fsf_set_contract_basic_parameters
164,7 → 168,6
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
178,10 → 181,7
@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
]
@retval FSF_ERR_BAD_ARGUMENT : if contract is NULL
*/
int
fsf_get_contract_basic_parameters
204,7 → 204,7
@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
222,17 → 222,13
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
@retval 0 if the operation is succesful
@retval FSF_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)))
]
is grater than the contracts maximum period))
 
@see sigexplanation
*/
251,10 → 247,9
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
]
@retval FSF_ERR_BAD_ARGUMENT if contract is NULL
 
@see fsf_set_contract_timing_requirements
*/
int
fsf_get_contract_timing_requirements
274,7 → 269,23
 
 
/**
\defgroup synch Synchronization objects
\ingroup coremodule
 
\defgroup core_synch Synchronization objects
 
These objects are used to synchronize threads belonging to bounded
workload servers.
 
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.
 
*/
/*@{*/
/**
293,55 → 304,50
variable managed by the scheduler, and returns a handle to it in
the variable pointed to by synch_handle.
@param[out] pointer to the variable that will contain the handle to the
newly created synchronization object
@param[out] synch_handle pointer to the variable that will contain
the handle to the newly created synchronization object
 
@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
]
 
@retval 0 if the operation is succesful
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0
@retval FSF_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
objects in the system has already exceeded the maximum
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
scheduled under the FSF
@retval 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.
specified as parameter. If there is at least one server waiting on
the synchronization object, the corresponding thread is unblocked,
and the server rules for budget recharging apply.
 
[JULIO: all the ocurrrences of the word "thread" should be changed
by "server" in the paragraph above
]
If more than one server is waiting, just one of them is woken.
However, which one is woken is implementation dependent.
 
If no thread is waiting on the synchronization object, the
notification is queued.
 
@param [in] synch_handle the handle of the synchronization object to
notify.
 
@returns 0 if the operation is completed succesfully
@returns 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
]
@retval 0 if the operation is completed succesfully
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread
is not scheduled under the FSF
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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
@see fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job
*/
int
fsf_signal_synch_obj
357,33 → 363,22
@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
@retval 0 if the operation is succesful
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
@retval 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
]
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
 
@sa fsf_create_synch_obj
@see 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
////////////////////////////////////////////////////
393,13 → 388,7
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??)
such threads has to be scheduled.
 
As an effect, the system will make the current server's budget zero
for the remainder of the server's period, and will not replenish
437,7 → 426,7
parameter is set to NULL, no action is
taken.
 
@param [out] was_budget_overrun upon return of this function, the
@param [out] was_budget_overran 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
444,24 → 433,19
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
@retval 0 if the operation is succesful
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is
not scheduled under the FSF
@retval FSF_ERR_UNBOUND 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
]
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not
FSF_BOUNDED
 
@sa fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job
 
*/
int
fsf_schedule_timed_job
471,7 → 455,6
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
482,34 → 465,62
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.
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
]
@param [in] synch_handle handle of the synchronization object
 
@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_overran 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.
 
@retval 0 if the operation is succesful
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
running
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of
the FSF main scheduler
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread
is not scheduled under the FSF
@retval FSF_ERR_UNBOUND if the calling thread does not have
a valid server bound to it
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not
FSF_BOUNDED or the synch_handle given is not valid
 
@sa fsf_schedule_triggered_job, fsf_schedule_timed_job
 
*/
int
fsf_schedule_triggered_job
525,20 → 536,19
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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction
of the FSF main scheduler
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is
not scheduled under the FSF
@retval FSF_ERR_UNBOUND 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
]
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not
FSF_BOUNDED, the synch_handle given is not valid or the abs_timeout
argument is NULL or its value is in the past
 
@see fsf_schedule_triggered_job
*/
int
fsf_timed_schedule_triggered_job
550,9 → 560,6
bool *was_deadline_missed,
bool *was_budget_overran);
 
 
 
 
/*@}*/
 
///////////////////////////////////////////////////////////////////
560,13 → 567,13
///////////////////////////////////////////////////////////////////
 
/**
\defgroup negotiate Negotiate contract functions
\ingroup coremodule
 
\defgroup core_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)
a server.
*/
/*@{*/
 
582,7 → 589,6
*/
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
589,27 → 595,31
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.
present in the system.
 
[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)
]
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.
 
@param [in] contract pointer to the contract
@param [out] server server id
 
@retval 0 if the call is succesful
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
running
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF
main scheduler
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD
if the calling thread is not scheduled
under the FSF
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments
are NULL
*/
int
fsf_negotiate_contract
616,7 → 626,6
(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
625,26 → 634,32
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 input parameter.
 
The attr parameter is overwritten as necessary to introduce the
adequate scheduling attributes, according to the information given
in the contract.
 
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
If the contract is rejected, the thread is not created and the
corresponding error is returned.
 
@param [in] contract pointer to the contract
@param [out] server server id
@param [out] thread thread id
@param [in] attr threads attributes
@param [in] thread_code pointer to the function that implements
the thread
@param [in] arg arguments for the thread
 
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments are NULL
@retval FSF_ERR_CONTRACT_REJECTED if the contract is rejected
It may also return all the errors that may be returned by the
pthread_create()POSIX function call
]
@retval others it may also return all the errors that may be returned
by the pthread_create()POSIX function call
 
*/
int
675,15 → 690,15
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
@param [in] contract pointer to the contract
@param [out] server id
@retval 0 if the contract negotation is succesful
@retval 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
]
 
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments
are NULL
@retval FSF_ERR_CONTRACT_REJECTED if the contract is rejected.
*/
int
fsf_negotiate_contract_for_myself
692,11 → 707,10
 
 
/**
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.
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, and error is returned.
 
It fails if the server's policy is different than FSF_NONE, or if
there is already a thread bound to this server
706,18 → 720,19
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
@param [in] server id
@param [in] thread id
 
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction
of the FSF main scheduler
@retval 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
@retval 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
]
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server
is not valid
@retval FSF_ERR_ALREADY_BOUND if the thread is already bound to
another server.
 
*/
int
738,18 → 753,18
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
@param [in] thread thread id
 
@retval 0 if the operation is succesful
@retval 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
@retval FSF_ERR_BAD_ARGUMENT if the given thread does not exist
@retval 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
@retval 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
@retval FSF_ERR_NOT_BOUND if the given thread does not have a valid
server bound to it
]
 
*/
int
fsf_unbind_thread_from_server (pthread_t thread);
760,15 → 775,16
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
@param [in] thread thread id
@param [out] server server
 
@retval 0 if the operation is succesful
@return 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
@return FSF_ERR_UNBOUND 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
@return FSF_ERR_BAD_ARGUMENT if the given thread does not exist or the
server argument is NULL
]
 
*/
int
fsf_get_server
780,16 → 796,18
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
@param [in] server server id
@param [out] contract pointer to the contract structure
 
@retval 0 if the operation is succesful
@retval FSF_ERR_BAD_ARGUMENT if the contract argument is
NULL or the value of the server argument is not in range
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
has been cancelled or it is not valid
]
 
*/
int
fsf_get_contract
802,15 → 820,16
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
]
@param [in] server server id
 
@retval 0 if the operation is succesful
@retval FSF_ERR_BAD_ARGUMENT if the value of server is not in range
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
scheduled under the FSF
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
running
@retval 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);
828,16 → 847,18
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
@param [in] new_contract a pointer to the new contract
@param [in] server server id
 
@retval 0 if the operation is succesful
@retval 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
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
running
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
has been cancelled or it is not valid
]
 
*/
int
fsf_renegotiate_contract
844,34 → 865,44
(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.
performed asynchronously and the calling thread may continue
executing normally. Of course, wheter the operation is performed
immediately or not depends on the relative priority of the service
thread and the calling thread, on the scheduler used, etc.
 
[ERR@RETURNED:
FSF_ERR_BAD_ARGUMENT : if the new_contract argument is NULL, the
When the renegotiation is completed, 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.
 
@param [in] new_contract pointer to the new contract to be negotiated
@param [in] server server id
@param [in] sig_notify NULL (no signal) or any POSIX signal
@param [in] sig_value a sigval structure that contains values to be
passed to the signal handler. Valid only if sig_notify
is different from NULL.
 
@retval 0 if the call is succesful
@retval 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
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
running
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
has been cancelled or it is not valid
]
 
*/
int
881,25 → 912,32
int sig_notify,
union sigval sig_value);
 
/**
Possible values returned by fsf_get_renegotiation_status
*/
typedef enum {FSF_IN_PROGRESS,
FSF_REJECTED,
FSF_ADMITTED}
fsf_renegotiation_status_t;
 
/**
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
requested.
 
[ERR@RETURNED:
FSF_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
@param [in] server server id
@param [out] renegotiation_status the status of the renegotiation;
 
@retval 0 if succesful completion;
@retval 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
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
running
@retval 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
906,6 → 944,62
(fsf_server_id_t server,
fsf_renegotiation_status_t *renegotiation_status);
 
 
//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 is is not valid.
 
@param [in] contracts_up list of contracts to negotiate
@param [in] servers_down list of contracts to be canceled
@param [out] servers_up list of server ids that have been created, they are
given in the same order as the contract_up list of contracts;
@param [out] accepted if the operation is succesful;
 
@retval 0 if succesful completion;
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF
main scheduler
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is
not scheduled under the FSF
@retval 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 *servers_down,
fsf_servers_group_t *servers_up,
bool *accepted);
 
 
/*@}*/
 
 
915,9 → 1009,20
 
 
/**
Returns true if the system is
configured with the on-line admission test enabled, or false
otherwise.
\ingroup coremodule
 
\defgroup core_sched_info Obtaining information from the scheduler.
 
This group of function is used to get informations from the
scheduler, like execution time of a task, remaining budget of a
server, etc.
 
@{
*/
 
/**
Returns true if the system is configured with the on-line admission
test enabled, or false otherwise.
*/
bool
fsf_is_admission_test_enabled();
927,16 → 1032,20
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
@param [in] server server id
@param [out] cpu_time pointer to a timespec structure that will contain
the cpu time consumed by the threads that are bound to the
specific server, since its creation.
 
@retval 0 if succesful completion
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
not in range or cpu_time is NULL
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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
946,18 → 1055,21
/**
This function stores in the variable pointed to by budget the
remaining execution-time budget associated with the specified
server
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
@param [in] server server id
@param [out] budget pointer to a timespec structure that will
contain the remaining budget
 
@retval 0 if succesful completion
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
not in range or budget is NULL
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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
966,21 → 1078,24
 
 
/**
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.
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
@param [in] server server id
@param [out] budget budget available for the current server instance
@param [out] period period available for the current server instance
 
@retval 0 if succesful completion
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
not in range, budget is NULL or period is NULL
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
running
@retval 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
988,47 → 1103,63
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
\ingroup coremodule
 
\defgroup core_service_thread Service Thread
 
These functions are to the initialization and tuning of the service
thread.
 
Implementation dependency: in the fixed priority implementation 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.
 
@{
*/
 
 
/**
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.
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
background.
 
The service thread starts with a default budget and period that are
configurable
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
@param [in] budget budget for the service thread
@param [in] period for the service thread
@param [out] accepted true is the change has been accepted
 
[ERR@RETURNED:
FSF_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
 
@retval 0 is the operation is succesful
@retval 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
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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
1040,16 → 1171,17
this function returns in the variables pointed by budget and
period, respectively, the current budget and period of the service
thread.
@param [out] budget current budget of the service thread
@param [out] period current 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
@retval FSF_ERR_BAD_ARGUMENT if any of the pointer arguments is NULL
@retval 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
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong
or not running
@retval 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
1056,109 → 1188,6
(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_