include/fosa_mutexes_and_condvars.h

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