Negotiate contract functions
[Core module]

Functions
int	fsf_negotiate_contract (const fsf_contract_parameters_t *contract, fsf_server_id_t *server)
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)
int	fsf_negotiate_contract_for_myself (const fsf_contract_parameters_t *contract, fsf_server_id_t *server)
int	fsf_bind_thread_to_server (fsf_server_id_t server, pthread_t thread)
int	fsf_unbind_thread_from_server (pthread_t thread)
int	fsf_get_server (pthread_t thread, fsf_server_id_t *server)
int	fsf_get_contract (fsf_server_id_t server, fsf_contract_parameters_t *contract)
int	fsf_cancel_contract (fsf_server_id_t server)
int	fsf_renegotiate_contract (const fsf_contract_parameters_t *new_contract, fsf_server_id_t server)
int	fsf_request_contract_renegotiation (const fsf_contract_parameters_t *new_contract, fsf_server_id_t server, int sig_notify, union sigval sig_value)
int	fsf_get_renegotiation_status (fsf_server_id_t server, fsf_renegotiation_status_t *renegotiation_status)
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)

---

Detailed Description

The following functions are used to create servers for a contract parameters specification and also to assign one or more threads to a server.

---

Function Documentation

int fsf_bind_thread_to_server (  fsf_server_id_t  server, pthread_t  thread )

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 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. Parameters: [in]  server id [in]  thread id Return values: 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_ALREADY_BOUND  if the given server has a thread already bound FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE  if the kind of workload in the contract is FSF_OVERHEAD

int fsf_cancel_contract (  fsf_server_id_t  server  )

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. Parameters: [in]  server server id Return values: 0  if the operation is succesful 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_get_contract (  fsf_server_id_t  server, fsf_contract_parameters_t *  contract )

This operation stores the contract parameters currently associated with the specified server in the variable pointed to by contract. It returns an error if the server id is incorrect. Parameters: [in]  server server id [out]  contract pointer to the contract structure Return values: 0  if the operation is succesful 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_renegotiation_status (  fsf_server_id_t  server, fsf_renegotiation_status_t *  renegotiation_status )

The operation reports on the status of the last renegotiation operation enqueued for the specified server. It is callable even after notification of the completion of such operation, if requested. Parameters: [in]  server server id [out]  renegotiation_status the status of the renegotiation; Return values: 0  if succesful completion; 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_server (  pthread_t  thread, fsf_server_id_t *  server )

This operation stores the Id of the server associated with the specified thread in the variable pointed to by server. It returns an error if the thread does not exist, it is not under the control of the scheduling framework, or is not bound. Parameters: [in]  thread thread id [out]  server server Return values: 0  if the operation is succesful Returns: FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled under the FSF FSF_ERR_NOT_BOUND 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_negotiate_contract (  const fsf_contract_parameters_t *  contract, fsf_server_id_t *  server )

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. Parameters: [in]  contract pointer to the contract [out]  server server id Return values: 0  if the call is succesful 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) FSF_ERR_CONTRACT_REJECTED  if the contract is rejected

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

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. 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. Parameters: [in]  contract pointer to the contract [out]  server id Return values: 0  if the contract negotation is succesful 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_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, 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 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. If the contract is rejected, the thread is not created and the corresponding error is returned. Parameters: [in]  contract pointer to the contract [out]  server server id [out]  thread thread id [in]  attr threads attributes [in]  thread_code pointer to the function that implements the thread [in]  arg arguments for the thread Return values: 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 others  it may also return all the errors that may be returned by the pthread_create()POSIX function call

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 )

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. Parameters: [in]  contracts_up list of contracts to negotiate [in]  servers_down list of contracts to be canceled [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; [out]  accepted if the operation is succesful; Return values: 0  if succesful completion; 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_renegotiate_contract (  const fsf_contract_parameters_t *  new_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. Parameters: [in]  new_contract a pointer to the new contract [in]  server server id Return values: 0  if the operation is succesful 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 FSF_ERR_REJECTED_CONTRACT  if the renegotiation fails

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 enqueues a renegotiate operation for an existing server, and returns immediately. The renegotiate operation is 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. 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. Parameters: [in]  new_contract pointer to the new contract to be negotiated [in]  server server id [in]  sig_notify NULL (no signal) or any POSIX signal [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. Return values: 0  if the call is succesful 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_unbind_thread_from_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. Parameters: [in]  thread thread id Return values: 0  if the operation is succesful 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  if the given thread does not have a valid server bound to it

---