src_marte/fosa_mutexes_and_condvars.c

   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 // -----------------------------------------------------------------------
  41 //fosa_mutexes_and_condvars.c
  42 //==============================================
  43 //  ********  ******    ********  **********
  44 //  **///// /**    **  **//////  /**     /**
  45 //  **      /**    ** /**        /**     /**
  46 //  ******* /**    ** /********* /**********
  47 //  **////  /**    ** ////////** /**//////**
  48 //  **      /**    **        /** /**     /**
  49 //  **      /**    **  ********  /**     /**
  50 //  //       /******/  ////////   //      //
  51 //
  52 // FOSA(Frescor Operating System Adaptation layer)
  53 //================================================
  54
  55 #include "fosa_mutexes_and_condvars.h"
  56
  57 #include <pthread.h>
  58 #include <stdio.h>
  59
  60 #include <misc/error_checks.h>
  61
  62
  63
  64 /*******************************************************
  65  * Mutexes with priority ceiling
  66  ******************************************************/
  67
  68 /**
  69  * fosa_mutex_init()
  70  *
  71  * Initialize a frsh mutex
  72  *
  73  * The mutex pointed to by mutex is initialized as a mutex using
  74  * the priority ceiling protocol. A priority ceiling of prioceiling
  75  * is assigned to this mutex.
  76  *
  77  * Returns 0 if successful; otherwise it returns an error code:
  78  *    EINVAL: the value of prioceiling is invalid
  79  *    EAGAIN: the system lacked the necessary resources to create the mutex
  80  *    ENOMEM: Insufficient memory exists to initialize the mutex
  81  *    EBUSY:  The system has detected an attempt to reinitialize the mutex
  82  *
  83  * Alternatively, in case of error the implementation is allowed to
  84  * notify it to the system console and then terminate the FRSH
  85  * implementation and dependant applications
  86  **/
  87 int fosa_mutex_init(frsh_mutex_t *mutex, int prioceiling)
  88 {
  89   pthread_mutexattr_t attr;
  90   int ret_value;
  91
  92   // create the attributes object and set the mutex to use the
  93   // priority ceiling protocol and the desired priority ceiling
  94   ret_value=pthread_mutexattr_init(&attr);
  95   if (ret_value!=0) return ret_value;
  96
  97   CHK(pthread_mutexattr_setprotocol(&attr,PTHREAD_PRIO_PROTECT));
  98   ret_value=pthread_mutexattr_setprioceiling(&attr,prioceiling);
  99
 100   if (ret_value==0) {
 101     // create the mutex
 102     ret_value=pthread_mutex_init(mutex,&attr);
 103   }
 104   // destroy the mutex attributes object
 105   pthread_mutexattr_destroy(&attr);
 106
 107   return ret_value;
 108 }
 109
 110 /**
 111  * fosa_mutex_destroy()
 112  *
 113  * Destroy a frsh mutex
 114  *
 115  * The mutex pointed to by mutex is destroyed
 116  *
 117  * Returns 0 if successful; otherwise it returns an error code:
 118  *    EINVAL: the value of mutex is invalid
 119  *    EBUSY:  The mutex is in use (is locked)
 120  *
 121  * Alternatively, in case of error the implementation is allowed to
 122  * notify it to the system console and then terminate the FRSH
 123  * implementation and dependant applications
 124  **/
 125 int fosa_mutex_destroy(frsh_mutex_t *mutex)
 126 {
 127   return pthread_mutex_destroy(mutex);
 128 }
 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  *     EINVAL: the value of mutex or prioceiling is invalid
 143  *
 144  * Alternatively, in case of error the implementation is allowed to
 145  * notify it to the system console and then terminate the FRSH
 146  * implementation and dependant applications
 147  **/
 148 int fosa_mutex_set_prioceiling
 149    (frsh_mutex_t *mutex, int new_ceiling, int *old_ceiling)
 150 {
 151   return pthread_mutex_setprioceiling(mutex,new_ceiling,old_ceiling);
 152 }
 153
 154 /**
 155  * fosa_mutex_get_prioceiling()
 156  *
 157  * Dynamically get the priority ceiling of a mutex
 158  *
 159  * This function copies into the variable pointed to by ceiling the
 160  * current priority ceiling of the mutex referenced by mutex
 161  *
 162  * Returns 0 if successful; otherwise it returns an error code:
 163  *     EINVAL: the value of mutex is invalid
 164  *
 165  * Alternatively, in case of error the implementation is allowed to
 166  * notify it to the system console and then terminate the FRSH
 167  * implementation and dependant applications
 168  **/
 169 int fosa_mutex_get_prioceiling(const frsh_mutex_t *mutex, int *ceiling)
 170 {
 171   return pthread_mutex_getprioceiling(mutex,ceiling);
 172 }
 173
 174 /**
 175  * fosa_mutex_lock()
 176  *
 177  * Lock a mutex
 178  *
 179  * This function locks the mutex specified by mutex. If it is already
 180  * locked, the calling thread blocks until the mutex becomes
 181  * available. The operation returns with the mutex in the locked
 182  * state, with the calling thread as its owner.
 183  *
 184  * Returns 0 if successful; otherwise it returns an error code:
 185  *    EINVAL: the value of mutex is invalid, or the priority of the
 186  *            calling thread is higher than the priority ceiling of the mutex
 187  *    EDEADLK: the current thread already owns this mutex
 188  *
 189  * Alternatively, in case of error the implementation is allowed to
 190  * notify it to the system console and then terminate the FRSH
 191  * implementation and dependant applications
 192  **/
 193 int fosa_mutex_lock(frsh_mutex_t *mutex)
 194 {
 195   return pthread_mutex_lock(mutex);
 196 }
 197
 198 /**
 199  * fosa_mutex_trylock()
 200  *
 201  * Try locking a mutex
 202  *
 203  * This function is identical to fosa_mutex_lock() except that if the
 204  * mutex is already locked the call returns immediately with an error
 205  * indication.
 206  *
 207  * Returns 0 if successful; otherwise it returns an error code:
 208  *    EINVAL: the value of mutex is invalid, or the priority of the
 209  *            calling thread is higher than the priority ceiling of the mutex
 210  *    EBUSY: the mutex was already locked
 211  *
 212  * Alternatively, except for 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(frsh_mutex_t *mutex)
 217 {
 218   return pthread_mutex_trylock(mutex);
 219 }
 220
 221 /**
 222  * fosa_mutex_unlock()
 223  *
 224  * Unlock a mutex
 225  *
 226  * This function must be called by the owner of the mutex referenced
 227  * by mutex, to unlock it. If there are threads blocked on the mutex
 228  * the mutex becomes available and the highest priority thread is
 229  * awakened to acquire the mutex.
 230  *
 231  * Returns 0 if successful; otherwise it returns an error code:
 232  *     EINVAL: the value of mutex is invalid
 233  *     EPERM: the calling thread is not the owner of the mutex
 234  *
 235  * Alternatively, except for EBUSY, in case of error the
 236  * implementation is allowed to notify it to the system console and
 237  * then terminate the FRSH implementation and dependant applications
 238  **/
 239 int fosa_mutex_unlock(frsh_mutex_t *mutex)
 240 {
 241   return pthread_mutex_unlock(mutex);
 242 }
 243
 244
 245 /**********************
 246  * Condition variables
 247  *********************/
 248
 249 /**
 250  * fosa_cond_init()
 251  *
 252  * Initiatize a condition variable
 253  *
 254  * The condition variable referenced by cond is initialized with
 255  * the attributes required by the FOSA implementation.
 256  *
 257  *  Returns 0 if successful; otherwise it returns an error code:
 258  *     EAGAIN: the system lacked the necessary resources to create the
 259  *             condition variable
 260  *     ENOMEM: Insufficient memory exists to initialize the condition variable
 261  *     EBUSY:  The system has detected an attempt to reinitialize the
 262  *             condition variable
 263  *
 264  * Alternatively, in case of error the implementation is allowed to
 265  * notify it to the system console and then terminate the FRSH
 266  * implementation and dependant applications
 267  **/
 268 int fosa_cond_init(fosa_cond_t *cond)
 269 {
 270   // initialize condition variable with default attributes
 271   return pthread_cond_init(cond,NULL);
 272 }
 273
 274 /**
 275  * fosa_cond_destroy()
 276  *
 277  * Destroy a condition variable
 278  *
 279  * The condition variable pointed to by cond is destroyed
 280  *
 281  * Returns 0 if successful; otherwise it returns an error code:
 282  *     EINVAL: the value of cond is invalid
 283  *     EBUSY:  The condition variable is in use (a thread is waiting on it)
 284  *
 285  * Alternatively, in case of error the implementation is allowed to
 286  * notify it to the system console and then terminate the FRSH
 287  * implementation and dependant applications
 288  **/
 289 int fosa_cond_destroy(fosa_cond_t *cond)
 290 {
 291   return pthread_cond_destroy(cond);
 292 }
 293
 294 /**
 295  * fosa_cond_signal()
 296  *
 297  * Signal a condition variable
 298  *
 299  * This call unblocks at least one of the threads that are waiting on
 300  * the condition variable referenced by cond. If there are no threads
 301  * waiting, the function has no effect
 302  *
 303  * Returns 0 if successful; otherwise it returns an error code:
 304  *     EINVAL: the value of cond is invalid
 305  *
 306  * Alternatively, in case of error the implementation is allowed to
 307  * notify it to the system console and then terminate the FRSH
 308  * implementation and dependant applications
 309  **/
 310 int fosa_cond_signal(fosa_cond_t *cond)
 311 {
 312   return pthread_cond_signal(cond);
 313 }
 314
 315 /**
 316  * fosa_cond_broadcast()
 317  *
 318  * Broadcast a condition variable
 319  *
 320  * This call unblocks all of the threads that are waiting on the
 321  * condition variable referenced by cond. If there are no threads
 322  * waiting, the function has no effect.
 323  *
 324  * Returns 0 if successful; otherwise it returns an error code:
 325  *     EINVAL: the value of cond is invalid
 326  *
 327  * Alternatively, in case of error the implementation is allowed to
 328  * notify it to the system console and then terminate the FRSH
 329  * implementation and dependant applications
 330  **/
 331 int fosa_cond_broadcast(fosa_cond_t *cond)
 332 {
 333   return pthread_cond_broadcast(cond);
 334 }
 335
 336 /**
 337  * fosa_cond_wait()
 338  *
 339  * Wait at a condition variable
 340  *
 341  * This call is used to block on the condition variable referenced by
 342  * cond. It shall be called with the mutex referenced by mutex
 343  * locked. The function releases the mutex and blocks the calling
 344  * thread until the condition is signalled by some other thread and
 345  * the calling thread is awakened. Then it locks the mutex and
 346  * returns with the mutex locked by the calling thread.
 347  *
 348  * Returns 0 if successful; otherwise it returns an error code:
 349  *    EINVAL: the value of cond or mutex is invalid, or different
 350  *            mutexes were used for concurrent wait operations on cond, or
 351  *            the mutex was not owned by the calling thread
 352  *
 353  * Alternatively, in case of error the implementation is allowed to
 354  * notify it to the system console and then terminate the FRSH
 355  * implementation and dependant applications
 356  **/
 357 int fosa_cond_wait(fosa_cond_t *cond, frsh_mutex_t *mutex)
 358 {
 359   return pthread_cond_wait(cond,mutex);
 360 }
 361
 362 /**
 363  * fosa_cond_timedwait()
 364  *
 365  * Wait at a condition variable, with a timeout
 366  *
 367  * This function is equal to fosa_cond_wait(), except that the maximum
 368  * wait time is limited to the absolute time referenced by abstime, as
 369  * measured by the FOSA_CLOCK_REALTIME clock.
 370  *
 371  * Returns 0 if successful; otherwise it returns an error code:
 372  *     EINVAL: the value of cond or mutex or abstime is invalid, or different
 373  *             mutexes were used for concurrent wait operations on cond, or
 374  *             the mutex was not owned by the calling thread
 375  *     ETIMEDOUT: the timeout expired
 376  *
 377  * Alternatively, except for ETIMEDOUT, in case of error the
 378  * implementation is allowed to notify it to the system console and
 379  * then terminate the FRSH implementation and dependant applications
 380  **/
 381 int fosa_cond_timedwait(fosa_cond_t *cond, frsh_mutex_t *mutex,
 382       const struct timespec *abstime)
 383 {
 384   return pthread_cond_timedwait(cond,mutex,abstime);
 385 }