include/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 #include "fosa_types.h"
  66
  67 /**
  68  * @defgroup mutexesandcondvars Mutexes and Condvars
  69  * @ingroup fosa
  70  *
  71  * This module defines the types and functions to abstract mutexes and
  72  * conditional variables for the FRSH implementation.
  73  *
  74  * @{
  75  **/
  76
  77
  78 /*******************************************************
  79  * Mutexes with priority ceiling
  80  ******************************************************/
  81
  82 /**
  83  * fosa_mutex_init()
  84  *
  85  * Initialize a frsh mutex
  86  *
  87  * The mutex pointed to by mutex is initialized as a mutex using
  88  * the priority ceiling protocol. A priority ceiling of prioceiling
  89  * is assigned to this mutex.
  90  *
  91  * Returns 0 if successful; otherwise it returns an error code:
  92  *
  93  * FOSA_EINVAL: the value of prioceiling is invalid \n
  94  * FOSA_EAGAIN: the system lacked the necessary resources to create
  95  *                the mutex \n
  96  * FOSA_ENOMEM: Insufficient memory exists to initialize the mutex \n
  97  * FOSA_EBUSY:  The system has detected an attempt to reinitialize the mutex
  98  *
  99  * Alternatively, in case of error the implementation is allowed to
 100  * notify it to the system console and then terminate the FRSH
 101  * implementation and dependant applications
 102  **/
 103 int fosa_mutex_init(frsh_mutex_t *mutex, int prioceiling);
 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  *
 114  *    FOSA_EINVAL: the value of mutex is invalid \n
 115  *    FOSA_EBUSY:  The mutex is in use (is locked)\n
 116  *
 117  * Alternatively, in case of error the implementation is allowed to
 118  * notify it to the system console and then terminate the FRSH
 119  * implementation and dependant applications
 120  **/
 121 int fosa_mutex_destroy(frsh_mutex_t *mutex);
 122
 123 /**
 124  * fosa_mutex_set_prioceiling()
 125  *
 126  * Dynamically set the priority ceiling of a mutex
 127  *
 128  * This function locks the mutex (blocking the calling thread if
 129  * necessary) and after it is locked it changes its priority ceiling
 130  * to the value specified by new_ceiling, and then it unlocks the
 131  * mutex. The previous value of the ceiling is returned in
 132  * old_ceiling.
 133  *
 134  * Returns 0 if successful; otherwise it returns an error code:
 135  *
 136  *     FOSA_EINVAL: the value of mutex or prioceiling is invalid \n
 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
 145 /**
 146  * fosa_mutex_get_prioceiling()
 147  *
 148  * Dynamically get the priority ceiling of a mutex
 149  *
 150  * This function copies into the variable pointed to by ceiling the
 151  * current priority ceiling of the mutex referenced by mutex
 152  *
 153  * Returns 0 if successful; otherwise it returns an error code:
 154  *
 155  *     FOSA_EINVAL: the value of mutex is invalid \n
 156  *
 157  * Alternatively, in case of error the implementation is allowed to
 158  * notify it to the system console and then terminate the FRSH
 159  * implementation and dependant applications
 160  **/
 161 int fosa_mutex_get_prioceiling(const frsh_mutex_t *mutex, int *ceiling);
 162
 163 /**
 164  * fosa_mutex_lock()
 165  *
 166  * Lock a mutex
 167  *
 168  * This function locks the mutex specified by mutex. If it is already
 169  * locked, the calling thread blocks until the mutex becomes
 170  * available. The operation returns with the mutex in the locked
 171  * state, with the calling thread as its owner.
 172  *
 173  * Returns 0 if successful; otherwise it returns an error code: \n
 174  *
 175  *    FOSA_EINVAL: the value of mutex is invalid, or the priority of the
 176  *            calling thread is higher than the priority ceiling of
 177  *            the mutex \n
 178  *
 179  *    FOSA_EDEADLK: the current thread already owns this mutex \n
 180  *
 181  * Alternatively, in case of error the implementation is allowed to
 182  * notify it to the system console and then terminate the FRSH
 183  * implementation and dependant applications
 184  **/
 185 int fosa_mutex_lock(frsh_mutex_t *mutex);
 186
 187 /**
 188  * fosa_mutex_trylock()
 189  *
 190  * Try locking a mutex
 191  *
 192  * This function is identical to fosa_mutex_lock() except that if the
 193  * mutex is already locked the call returns immediately with an error
 194  * indication.
 195  *
 196  * Returns 0 if successful; otherwise it returns an error code:
 197  *    FOSA_EINVAL: the value of mutex is invalid, or the priority of the
 198  *       calling thread is higher than the priority ceiling of the
 199  *       mutex \n
 200  *    FOSA_EBUSY: the mutex was already locked \n
 201  *
 202  * Alternatively, except for FOSA_EBUSY, in case of error the
 203  * implementation is allowed to notify it to the system console and
 204  * then terminate the FRSH implementation and dependant applications
 205  **/
 206 int fosa_mutex_trylock(frsh_mutex_t *mutex);
 207
 208 /**
 209  * fosa_mutex_unlock()
 210  *
 211  * Unlock a mutex
 212  *
 213  * This function must be called by the owner of the mutex referenced
 214  * by mutex, to unlock it. If there are threads blocked on the mutex
 215  * the mutex becomes available and the highest priority thread is
 216  * awakened to acquire the mutex.
 217  *
 218  * Returns 0 if successful; otherwise it returns an error code:
 219  *     FOSA_EINVAL: the value of mutex is invalid
 220  *     FOSA_EPERM: the calling thread is not the owner of the mutex
 221  *
 222  * Alternatively, except for FOSA_EBUSY, in case of error the
 223  * implementation is allowed to notify it to the system console and
 224  * then terminate the FRSH implementation and dependant applications
 225  **/
 226 int fosa_mutex_unlock(frsh_mutex_t *mutex);
 227
 228
 229 /**********************
 230  * Condition variables
 231  *********************/
 232
 233 /**
 234  * fosa_cond_init()
 235  *
 236  * Initiatize a condition variable
 237  *
 238  * The condition variable referenced by cond is initialized with
 239  * the attributes required by the FOSA implementation.
 240  *
 241  *  Returns 0 if successful; otherwise it returns an error code:
 242  *     FOSA_EAGAIN: the system lacked the necessary resources to create the
 243  *             condition variable
 244  *     FOSA_ENOMEM: Insufficient memory exists to initialize the condition variable
 245  *     FOSA_EBUSY:  The system has detected an attempt to reinitialize the
 246  *             condition variable
 247  *
 248  * Alternatively, in case of error the implementation is allowed to
 249  * notify it to the system console and then terminate the FRSH
 250  * implementation and dependant applications
 251  **/
 252 int fosa_cond_init(fosa_cond_t *cond);
 253
 254 /**
 255  * fosa_cond_destroy()
 256  *
 257  * Destroy a condition variable
 258  *
 259  * The condition variable pointed to by cond is destroyed
 260  *
 261  * Returns 0 if successful; otherwise it returns an error code:
 262  *     FOSA_EINVAL: the value of cond is invalid
 263  *     FOSA_EBUSY:  The condition variable is in use (a thread is waiting on it)
 264  *
 265  * Alternatively, in case of error the implementation is allowed to
 266  * notify it to the system console and then terminate the FRSH
 267  * implementation and dependant applications
 268  **/
 269 int fosa_cond_destroy(fosa_cond_t *cond);
 270
 271 /**
 272  * fosa_cond_signal()
 273  *
 274  * Signal a condition variable
 275  *
 276  * This call unblocks at least one of the threads that are waiting on
 277  * the condition variable referenced by cond. If there are no threads
 278  * waiting, the function has no effect
 279  *
 280  * Returns 0 if successful; otherwise it returns an error code:
 281  *     FOSA_EINVAL: the value of cond is invalid
 282  *
 283  * Alternatively, in case of error the implementation is allowed to
 284  * notify it to the system console and then terminate the FRSH
 285  * implementation and dependant applications
 286  **/
 287 int fosa_cond_signal(fosa_cond_t *cond);
 288
 289 /**
 290  * fosa_cond_broadcast()
 291  *
 292  * Broadcast a condition variable
 293  *
 294  * This call unblocks all of the threads that are waiting on the
 295  * condition variable referenced by cond. If there are no threads
 296  * waiting, the function has no effect.
 297  *
 298  * Returns 0 if successful; otherwise it returns an error code:
 299  *     FOSA_EINVAL: the value of cond is invalid
 300  *
 301  * Alternatively, in case of error the implementation is allowed to
 302  * notify it to the system console and then terminate the FRSH
 303  * implementation and dependant applications
 304  **/
 305 int fosa_cond_broadcast(fosa_cond_t *cond);
 306
 307 /**
 308  * fosa_cond_wait()
 309  *
 310  * Wait at a condition variable
 311  *
 312  * This call is used to block on the condition variable referenced by
 313  * cond. It shall be called with the mutex referenced by mutex
 314  * locked. The function releases the mutex and blocks the calling
 315  * thread until the condition is signalled by some other thread and
 316  * the calling thread is awakened. Then it locks the mutex and
 317  * returns with the mutex locked by the calling thread.
 318  *
 319  * Returns 0 if successful; otherwise it returns an error code:
 320  *    FOSA_EINVAL: the value of cond or mutex is invalid, or different
 321  *            mutexes were used for concurrent wait operations on cond, or
 322  *            the mutex was not owned by the calling thread
 323  *
 324  * Alternatively, in case of error the implementation is allowed to
 325  * notify it to the system console and then terminate the FRSH
 326  * implementation and dependant applications
 327  **/
 328 int fosa_cond_wait(fosa_cond_t *cond, frsh_mutex_t *mutex);
 329
 330 /**
 331  * fosa_cond_timedwait()
 332  *
 333  * Wait at a condition variable, with a timeout
 334  *
 335  * This function is equal to fosa_cond_wait(), except that the maximum
 336  * wait time is limited to the absolute time referenced by abstime, as
 337  * measured by the FOSA_CLOCK_REALTIME clock.
 338  *
 339  * Returns 0 if successful; otherwise it returns an error code:
 340  *     FOSA_EINVAL: the value of cond or mutex or abstime 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  *     FOSA_ETIMEDOUT: the timeout expired
 344  *
 345  * Alternatively, except for FOSA_ETIMEDOUT, in case of error the
 346  * implementation is allowed to notify it to the system console and
 347  * then terminate the FRSH implementation and dependant applications
 348  **/
 349 int fosa_cond_timedwait(fosa_cond_t *cond, frsh_mutex_t *mutex,
 350       const struct timespec *abstime);
 351
 352 /*@}*/
 353
 354
 355
 356
 357 #endif      /* !FOSA_MUTEX_AND_CONDVARS_H_ */