src_rtlinux/fosa_mutexes_and_condvars.h

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