include/fosa_mutexes_and_condvars.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2009 FRESCOR consortium partners:
   3 //
   4 //    Universidad de Cantabria,              SPAIN
   5 //    University of York,                    UK
   6 //    Scuola Superiore Sant'Anna,            ITALY
   7 //    Kaiserslautern University,             GERMANY
   8 //    Univ. Politécnica  Valencia,           SPAIN
   9 //    Czech Technical University in Prague,  CZECH REPUBLIC
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org for a link to partners' websites
  17 //
  18 //           FRESCOR project (FP6/2005/IST/5-034026) is funded
  19 //        in part by the European Union Sixth Framework Programme
  20 //        The European Union is not liable of any use that may be
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 //   FSF API web pages: http://marte.unican.es/fsf/docs
  32 //                      http://shark.sssup.it/contrib/first/docs/
  33 //
  34 //   This file is part of FOSA (Frsh Operating System Adaption)
  35 //
  36 //  FOSA is free software; you can redistribute it and/or modify it
  37 //  under terms of the GNU General Public License as published by the
  38 //  Free Software Foundation; either version 2, or (at your option) any
  39 //  later version.  FOSA is distributed in the hope that it will be
  40 //  useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  41 //  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  42 //  General Public License for more details. You should have received a
  43 //  copy of the GNU General Public License along with FOSA; see file
  44 //  COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
  45 //  Cambridge, MA 02139, USA.
  46 //
  47 //  As a special exception, including FOSA header files in a file,
  48 //  instantiating FOSA generics or templates, or linking other files
  49 //  with FOSA objects to produce an executable application, does not
  50 //  by itself cause the resulting executable application to be covered
  51 //  by the GNU General Public License. This exception does not
  52 //  however invalidate any other reasons why the executable file might be
  53 //  covered by the GNU Public License.
  54 // -----------------------------------------------------------------------
  55 //fosa_mutexes_and_condvars.h
  56 //==============================================
  57 //  ********  ******    ********  **********
  58 //  **///// /**    **  **//////  /**     /**
  59 //  **      /**    ** /**        /**     /**
  60 //  ******* /**    ** /********* /**********
  61 //  **////  /**    ** ////////** /**//////**
  62 //  **      /**    **        /** /**     /**
  63 //  **      /**    **  ********  /**     /**
  64 //  //       /******/  ////////   //      //
  65 //
  66 // FOSA(Frescor Operating System Adaptation layer)
  67 //================================================
  68
  69 #ifndef         FOSA_MUTEX_AND_CONDVARS_H_
  70 #define         FOSA_MUTEX_AND_CONDVARS_H_
  71
  72
  73 #include "fosa_types.h"
  74
  75 FOSA_CPP_BEGIN_DECLS
  76
  77 /**
  78  * @defgroup mutexesandcondvars Mutexes and Condvars
  79  * @ingroup fosa
  80  *
  81  * This module defines the types and functions to abstract mutexes and
  82  * conditional variables for the FRSH implementation.
  83  *
  84  * @{
  85  **/
  86
  87
  88 /*******************************************************
  89  * Mutexes with priority ceiling
  90  ******************************************************/
  91
  92 /**
  93  * fosa_mutex_init()
  94  *
  95  * Initialize a frsh mutex
  96  *
  97  * The mutex pointed to by mutex is initialized as a mutex using
  98  * the priority ceiling protocol. A priority ceiling of prioceiling
  99  * is assigned to this mutex.
 100  *
 101  * Returns 0 if successful; otherwise it returns an error code:
 102  *
 103  * FOSA_EINVAL: the value of prioceiling is invalid \n
 104  * FOSA_EAGAIN: the system lacked the necessary resources to create
 105  *                the mutex \n
 106  * FOSA_ENOMEM: Insufficient memory exists to initialize the mutex \n
 107  * FOSA_EBUSY:  The system has detected an attempt to reinitialize the mutex
 108  *
 109  * Alternatively, in case of error the implementation is allowed to
 110  * notify it to the system console and then terminate the FRSH
 111  * implementation and dependant applications
 112  **/
 113 int fosa_mutex_init(fosa_mutex_t *mutex, int prioceiling);
 114
 115 /**
 116  * fosa_mutex_destroy()
 117  *
 118  * Destroy a frsh mutex
 119  *
 120  * The mutex pointed to by mutex is destroyed
 121  *
 122  * Returns 0 if successful; otherwise it returns an error code:
 123  *
 124  *    FOSA_EINVAL: the value of mutex is invalid \n
 125  *    FOSA_EBUSY:  The mutex is in use (is locked)\n
 126  *
 127  * Alternatively, in case of error the implementation is allowed to
 128  * notify it to the system console and then terminate the FRSH
 129  * implementation and dependant applications
 130  **/
 131 int fosa_mutex_destroy(fosa_mutex_t *mutex);
 132
 133 /**
 134  * fosa_mutex_set_prioceiling()
 135  *
 136  * Dynamically set the priority ceiling of a mutex
 137  *
 138  * This function locks the mutex (blocking the calling thread if
 139  * necessary) and after it is locked it changes its priority ceiling
 140  * to the value specified by new_ceiling, and then it unlocks the
 141  * mutex. The previous value of the ceiling is returned in
 142  * old_ceiling.
 143  *
 144  * Returns 0 if successful; otherwise it returns an error code:
 145  *
 146  *     FOSA_EINVAL: the value of mutex or prioceiling is invalid \n
 147  *
 148  * Alternatively, in case of error the implementation is allowed to
 149  * notify it to the system console and then terminate the FRSH
 150  * implementation and dependant applications
 151  **/
 152 int fosa_mutex_set_prioceiling
 153    (fosa_mutex_t *mutex, int new_ceiling, int *old_ceiling);
 154
 155 /**
 156  * fosa_mutex_get_prioceiling()
 157  *
 158  * Dynamically get the priority ceiling of a mutex
 159  *
 160  * This function copies into the variable pointed to by ceiling the
 161  * current priority ceiling of the mutex referenced by mutex
 162  *
 163  * Returns 0 if successful; otherwise it returns an error code:
 164  *
 165  *     FOSA_EINVAL: the value of mutex is invalid \n
 166  *
 167  * Alternatively, in case of error the implementation is allowed to
 168  * notify it to the system console and then terminate the FRSH
 169  * implementation and dependant applications
 170  **/
 171 int fosa_mutex_get_prioceiling(const fosa_mutex_t *mutex, int *ceiling);
 172
 173 /**
 174  * fosa_mutex_lock()
 175  *
 176  * Lock a mutex
 177  *
 178  * This function locks the mutex specified by mutex. If it is already
 179  * locked, the calling thread blocks until the mutex becomes
 180  * available. The operation returns with the mutex in the locked
 181  * state, with the calling thread as its owner.
 182  *
 183  * Returns 0 if successful; otherwise it returns an error code: \n
 184  *
 185  *    FOSA_EINVAL: the value of mutex is invalid, or the priority of the
 186  *            calling thread is higher than the priority ceiling of
 187  *            the mutex \n
 188  *
 189  *    FOSA_EDEADLK: the current thread already owns this mutex \n
 190  *
 191  * Alternatively, in case of error the implementation is allowed to
 192  * notify it to the system console and then terminate the FRSH
 193  * implementation and dependant applications
 194  **/
 195 int fosa_mutex_lock(fosa_mutex_t *mutex);
 196
 197 /**
 198  * fosa_mutex_trylock()
 199  *
 200  * Try locking a mutex
 201  *
 202  * This function is identical to fosa_mutex_lock() except that if the
 203  * mutex is already locked the call returns immediately with an error
 204  * indication.
 205  *
 206  * Returns 0 if successful; otherwise it returns an error code:
 207  *    FOSA_EINVAL: the value of mutex is invalid, or the priority of the
 208  *       calling thread is higher than the priority ceiling of the
 209  *       mutex \n
 210  *    FOSA_EBUSY: the mutex was already locked \n
 211  *
 212  * Alternatively, except for FOSA_EBUSY, in case of error the
 213  * implementation is allowed to notify it to the system console and
 214  * then terminate the FRSH implementation and dependant applications
 215  **/
 216 int fosa_mutex_trylock(fosa_mutex_t *mutex);
 217
 218 /**
 219  * fosa_mutex_unlock()
 220  *
 221  * Unlock a mutex
 222  *
 223  * This function must be called by the owner of the mutex referenced
 224  * by mutex, to unlock it. If there are threads blocked on the mutex
 225  * the mutex becomes available and the highest priority thread is
 226  * awakened to acquire the mutex.
 227  *
 228  * Returns 0 if successful; otherwise it returns an error code:
 229  *     FOSA_EINVAL: the value of mutex is invalid
 230  *     FOSA_EPERM: the calling thread is not the owner of the mutex
 231  *
 232  * Alternatively, except for FOSA_EBUSY, in case of error the
 233  * implementation is allowed to notify it to the system console and
 234  * then terminate the FRSH implementation and dependant applications
 235  **/
 236 int fosa_mutex_unlock(fosa_mutex_t *mutex);
 237
 238
 239 /**********************
 240  * Condition variables
 241  *********************/
 242
 243 /**
 244  * fosa_cond_init()
 245  *
 246  * Initiatize a condition variable
 247  *
 248  * The condition variable referenced by cond is initialized with
 249  * the attributes required by the FOSA implementation.
 250  *
 251  *  Returns 0 if successful; otherwise it returns an error code:
 252  *     FOSA_EAGAIN: the system lacked the necessary resources to create the
 253  *             condition variable
 254  *     FOSA_ENOMEM: Insufficient memory exists to initialize the condition variable
 255  *     FOSA_EBUSY:  The system has detected an attempt to reinitialize the
 256  *             condition variable
 257  *
 258  * Alternatively, in case of error the implementation is allowed to
 259  * notify it to the system console and then terminate the FRSH
 260  * implementation and dependant applications
 261  **/
 262 int fosa_cond_init(fosa_cond_t *cond);
 263
 264 /**
 265  * fosa_cond_destroy()
 266  *
 267  * Destroy a condition variable
 268  *
 269  * The condition variable pointed to by cond is destroyed
 270  *
 271  * Returns 0 if successful; otherwise it returns an error code:
 272  *     FOSA_EINVAL: the value of cond is invalid
 273  *     FOSA_EBUSY:  The condition variable is in use (a thread is waiting on it)
 274  *
 275  * Alternatively, in case of error the implementation is allowed to
 276  * notify it to the system console and then terminate the FRSH
 277  * implementation and dependant applications
 278  **/
 279 int fosa_cond_destroy(fosa_cond_t *cond);
 280
 281 /**
 282  * fosa_cond_signal()
 283  *
 284  * Signal a condition variable
 285  *
 286  * This call unblocks at least one of the threads that are waiting on
 287  * the condition variable referenced by cond. If there are no threads
 288  * waiting, the function has no effect
 289  *
 290  * Returns 0 if successful; otherwise it returns an error code:
 291  *     FOSA_EINVAL: the value of cond is invalid
 292  *
 293  * Alternatively, in case of error the implementation is allowed to
 294  * notify it to the system console and then terminate the FRSH
 295  * implementation and dependant applications
 296  **/
 297 int fosa_cond_signal(fosa_cond_t *cond);
 298
 299 /**
 300  * fosa_cond_broadcast()
 301  *
 302  * Broadcast a condition variable
 303  *
 304  * This call unblocks all of the threads that are waiting on the
 305  * condition variable referenced by cond. If there are no threads
 306  * waiting, the function has no effect.
 307  *
 308  * Returns 0 if successful; otherwise it returns an error code:
 309  *     FOSA_EINVAL: the value of cond is invalid
 310  *
 311  * Alternatively, in case of error the implementation is allowed to
 312  * notify it to the system console and then terminate the FRSH
 313  * implementation and dependant applications
 314  **/
 315 int fosa_cond_broadcast(fosa_cond_t *cond);
 316
 317 /**
 318  * fosa_cond_wait()
 319  *
 320  * Wait at a condition variable
 321  *
 322  * This call is used to block on the condition variable referenced by
 323  * cond. It shall be called with the mutex referenced by mutex
 324  * locked. The function releases the mutex and blocks the calling
 325  * thread until the condition is signalled by some other thread and
 326  * the calling thread is awakened. Then it locks the mutex and
 327  * returns with the mutex locked by the calling thread.
 328  *
 329  * Returns 0 if successful; otherwise it returns an error code:
 330  *    FOSA_EINVAL: the value of cond or mutex is invalid, or different
 331  *            mutexes were used for concurrent wait operations on cond, or
 332  *            the mutex was not owned by the calling thread
 333  *
 334  * Alternatively, in case of error the implementation is allowed to
 335  * notify it to the system console and then terminate the FRSH
 336  * implementation and dependant applications
 337  **/
 338 int fosa_cond_wait(fosa_cond_t *cond, fosa_mutex_t *mutex);
 339
 340 /**
 341  * fosa_cond_timedwait()
 342  *
 343  * Wait at a condition variable, with a timeout
 344  *
 345  * This function is equal to fosa_cond_wait(), except that the maximum
 346  * wait time is limited to the absolute time referenced by abstime, as
 347  * measured by the FOSA_CLOCK_ABSOLUTE clock.
 348  *
 349  * Returns 0 if successful; otherwise it returns an error code:
 350  *     FOSA_EINVAL: the value of cond or mutex or abstime is invalid, or different
 351  *             mutexes were used for concurrent wait operations on cond, or
 352  *             the mutex was not owned by the calling thread
 353  *     FOSA_ETIMEDOUT: the timeout expired
 354  *
 355  * Alternatively, except for FOSA_ETIMEDOUT, in case of error the
 356  * implementation is allowed to notify it to the system console and
 357  * then terminate the FRSH implementation and dependant applications
 358  **/
 359 int fosa_cond_timedwait(fosa_cond_t *cond, fosa_mutex_t *mutex,
 360       const fosa_abs_time_t *abstime);
 361
 362 /*@}*/
 363
 364
 365 FOSA_CPP_END_DECLS
 366
 367 #endif      /* !FOSA_MUTEX_AND_CONDVARS_H_ */