Synchronization objects
[Core module]

Functions
int	fsf_create_synch_obj (fsf_synch_obj_handle_t *synch_handle)
int	fsf_signal_synch_obj (fsf_synch_obj_handle_t synch_handle)
int	fsf_destroy_synch_obj (fsf_synch_obj_handle_t synch_handle)
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)
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)
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)

---

Detailed Description

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.

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.

---

Function Documentation

int fsf_create_synch_obj (  fsf_synch_obj_handle_t *  synch_handle  )

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. Parameters: out]  synch_handle pointer to the variable that will contain the handle to the newly created synchronization object Return values: 0  if the operation is succesful 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_destroy_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. Parameters: synch_handle  the handle to the synchronization object to be destroyed Return values: 0  if the operation is succesful FSF_ERR_INVALID_SYNCH_OBJ_HANDLE  is the handle is not valid 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 See also: fsf_create_synch_obj

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. 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. Parameters: [in]  abs_time absolute time at which the budget will be replenished [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. [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. [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. [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. Return values: 0  if the operation 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_NOT_BOUND  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 See also: fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job

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 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. Parameters: [in]  synch_handle handle of the synchronization object [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. [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. [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. [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. Return values: 0  if the operation is succesful FSF_ERR_INVALID_SYNCH_OBJ_HANDLE  if the synch_handle is not valid FSF_ERR_BAD_ARGUMENT  if synch_handle is 0 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  if the calling thread does not have a valid server bound to it FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE:  if the kind of workload of the server is not FSF_BOUNDED See also: fsf_schedule_triggered_job, fsf_schedule_timed_job

int fsf_signal_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 server waiting on the synchronization object, the corresponding thread is unblocked, and the server rules for budget recharging apply. 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. Parameters: [in]  synch_handle the handle of the synchronization object to notify. Return values: 0  if the operation is completed succesfully 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 See also: fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job

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 )

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 Return values: FSF_ERR_INVALID_SYNCH_OBJ_HANDLE  if the synch_handle is not valid 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  if the calling thread does not have a valid server bound to it FSF_ERR_BAD_ARGUMENT  if synch_handle is 0, 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 See also: fsf_schedule_triggered_job

---