resource/csdk/connectivity/common/inc/camutex.h

   1 /* ****************************************************************
   2  *
   3  * Copyright 2014 Samsung Electronics All Rights Reserved.
   4  *
   5  *
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *      http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  ******************************************************************/
  20
  21 /**
  22  * @file
  23  *
  24  * This file provides APIs related to mutex and semaphores.
  25  */
  26
  27 #ifndef CA_MUTEX_H_
  28 #define CA_MUTEX_H_
  29
  30 #include "cacommon.h"
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #endif /* __cplusplus */
  36
  37 typedef struct ca_mutex_internal *ca_mutex;
  38 typedef struct ca_cond_internal *ca_cond;
  39
  40 /**
  41  * Enums for ca_cond_wait_for return values
  42  */
  43 typedef enum
  44 {
  45    CA_WAIT_SUCCESS = 0,    /**< Condition Signal */
  46    CA_WAIT_INVAL = -1,     /**< Invalid Condition */
  47    CA_WAIT_TIMEDOUT = -2   /**< Condition Timed Out */
  48 } CAWaitResult_t;
  49
  50 /**
  51  * Creates new mutex.
  52  *
  53  * @return  Reference to newly created mutex, otherwise NULL.
  54  *
  55  */
  56 ca_mutex ca_mutex_new(void);
  57
  58 /**
  59  * Lock the mutex.
  60  *
  61  * @param  mutex  The mutex to be locked
  62  *
  63  */
  64 void ca_mutex_lock(ca_mutex mutex);
  65
  66 /**
  67  * Checks if the mutex can be locked.
  68  *
  69  * @param  mutex  The mutex to be locked
  70  *
  71  * @return  true if the mutex is not locked currently, otherwise false.
  72  *
  73  */
  74 bool ca_mutex_trylock(ca_mutex mutex);
  75
  76 /**
  77  * Unlock the mutex.
  78  *
  79  * @param  mutex  The mutex to be unlocked
  80  *
  81  */
  82 void ca_mutex_unlock(ca_mutex mutex);
  83
  84 /**
  85  * Free the mutex.
  86  *
  87  * @param  mutex  The mutex to be freed
  88  *
  89  */
  90 bool ca_mutex_free(ca_mutex mutex);
  91
  92 /**
  93  * Creates new condition.
  94  *
  95  * @return  Reference to newly created @ca_cond, otherwise NULL.
  96  *
  97  */
  98 ca_cond ca_cond_new(void);
  99
 100 /**
 101  * One of threads is woken up if multiple threads are waiting for @cond.
 102  *
 103  * @param  cond  The condtion to be signaled
 104  *
 105  */
 106 void ca_cond_signal(ca_cond cond);
 107
 108 /**
 109  * All of threads are woken up if multiple threads are waiting for @cond.
 110  *
 111  * @param  cond  The condtion to be signaled
 112  *
 113  */
 114 void ca_cond_broadcast(ca_cond cond);
 115
 116 /**
 117  * Waits until this thread woken up on @cond.
 118  *
 119  * @param  cond  The condtion to be wait for to signal
 120  * @param  mutex  The mutex which is currently locked from calling thread
 121  *
 122  */
 123 void ca_cond_wait(ca_cond cond, ca_mutex mutex);
 124
 125 /**
 126  * Waits until this thread woken up on @cond,
 127  * but not longer than the interval specified by microseconds.
 128  * The mutex is unlocked before falling asleep and locked again before resuming.
 129  * If microseconds is 0, ca_cond_wait_for() acts like ca_cond_wait().
 130  *
 131  * @param  cond  The condtion to be wait for to signal
 132  * @param  mutex  The mutex which is currently locked from calling thread
 133  * @param  microseconds  relative time for waiting, microseconds
 134  *
 135  * @return CA_WAIT_SUCCESS if the condition was signaled.
 136  *         CA_WAIT_TIMEDDOUT if wait period exceeded
 137  *         CA_WAIT_INVAL for invalid parameters
 138  *
 139  */
 140 CAWaitResult_t ca_cond_wait_for(ca_cond cond, ca_mutex mutex, uint64_t microseconds);
 141
 142 /**
 143  * Free the condition.
 144  *
 145  * @param  cond  The condition to be freed
 146  *
 147  */
 148 void ca_cond_free(ca_cond cond);
 149
 150 #ifdef __cplusplus
 151 } /* extern "C" */
 152 #endif /* __cplusplus */
 153
 154 #endif /* CA_MUTEX_H_ */
 155