Subversion Repositories shark

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

//

// FSF(FIRST Scheduling Framework) 

// shared objects functionality

//====================================================

#include <pthread.h>

#include "fsf_basic_types.h"

#include "fsf_core.h"

#ifndef _FSF_SHARED_OBJECTS_H_

#define _FSF_SHARED_OBJECTS_H_

#define FSF_SHARED_OBJECTS_MODULE_SUPPORTED       1

// These constants are defined in the fsf_configuration_parameters.h

// file:

//#define FSF_MAX_N_SHARED_OBJECTS    100

//#define FSF_MAX_N_CRITICAL_SECTIONS 20

//// The definition of this types is in fsf_basic_types.h

//

//// Shared object identifier (null character terminated string)

//typedef char  * fsf_shared_obj_id_t;     

//

//// Shared object handle (opaque type)

//typedef FSF_SHARED_OBJ_HANDLE_T_OPAQUE  fsf_shared_obj_handle_t; 

//

//// Critical section data

//typedef struct {

//   fsf_shared_obj_handle_t obj_handle;

//   struct timespec         wcet;  //Execution time

//} fsf_critical_section_data_t;

//

//// List of critical sections

//typedef struct {

//  int size; // = 0

//  fsf_critical_section_data_t  

//      section[FSF_MAX_N_CRITICAL_SECTIONS];

//} fsf_critical_sections_t;

//

/////////////////////////////////////////////////////

//           SHARED OBJECTS & OPERATIONS MANAGEMENT

/////////////////////////////////////////////////////

// fsf_init_shared_object: Initialization of shared objects. If the

// object identified by obj_id does not yet exist it is created, a

// handle to the object is returned in the variable pointed to by

// obj_handle, and the specified mutex is initialized with the

// appropriate attributes necessary for the current implementation.

// If the object already exists, the function fails.

/*

    [ERR@RETURNED:

     FSF_ERR_BAD_ARGUMENT : if obj_id, obj_handle, or mutex are NULL

     FSF_ERR_SHARED_OBJ_ALREADY_INITIALIZED : if the object identified

       by obj_id already exists

     It may also return any of the error codes that are returned by the

       pthread_mutex_init() POSIX function call

    ]

*/

int fsf_init_shared_object

   (fsf_shared_obj_id_t      obj_id,

    fsf_shared_obj_handle_t *obj_handle,

    pthread_mutex_t         *mutex);

// fsf_get_shared_object_handle: getting the handle of shared

// objects. If the object already exists a handle to the object is

// returned in the variable pointed to by obj_handle. Otherwise, an

// error code is returned by the function.

/*

    [ERR@RETURNED:

     FSF_ERR_BAD_ARGUMENT : if obj_id or obj_handle are NULL

     FSF_ERR_SHARED_OBJ_NOT_INITIALIZED : if the shared object identified

       by obj_id does not exist

     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

     It may also return any of the error codes that are returned by the

       pthread_mutex_init() POSIX function call

    ]

*/

int fsf_get_shared_object_handle

   (fsf_shared_obj_id_t      obj_id,

    fsf_shared_obj_handle_t *obj_handle);

// fsf_get_shared_object_mutex: getting the mutex of shared

// objects. If the object exists, a pointer to its associated mutex is

// returned in the variable pointed to by mutex. Otherwise, an error

// code is returned by the function.

/*

    [ERR@RETURNED:

     FSF_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL

     FSF_ERR_SHARED_OBJ_NOT_INITIALIZED : if the shared object identified

       by obj_id does not exist

     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_shared_object_mutex

   (fsf_shared_obj_handle_t  obj_handle,

    pthread_mutex_t          **mutex);

/////////////////////////////////////////////////////

//                       CONTRACT PARAMETERS

/////////////////////////////////////////////////////

//fsf_set_contract_synchronization_parameters: The operation updates

//the specified contract parameters object by setting its critical

//sections to the specified input parameter.

/*

    [ERR@RETURNED:

     FSF_ERR_BAD_ARGUMENT :  if any of the pointers is NULL or

       the size of the critical_sections structure is less than zero

       or grater than FSF_MAX_N_CRITICAL_SECTIONS

    ]

*/

int

fsf_set_contract_synchronization_parameters

  (fsf_contract_parameters_t     *contract,

   const fsf_critical_sections_t *critical_sections);

//fsf_get_contract_synchronization_parameters: The operation obtains

//from the specified contract parameters object its critical sections,

//and copies them to the places pointed to by the specified input

//parameter.  Only those critical_section_data records that are in use

//in the critical_sections structure are copied (according to its size

//field).

/*

    [ERR@RETURNED:

     FSF_ERR_BAD_ARGUMENT :  if any of the pointers is NULL

    ]

*/

int

fsf_get_contract_synchronization_parameters

  (const fsf_contract_parameters_t *contract,

   fsf_critical_sections_t         *critical_sections);

#endif // _FSF_SHARED_OBJECTS_H_