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  * Unlock the mutex.
  68  *
  69  * @param  mutex  The mutex to be unlocked.
  70  *
  71  */
  72 void ca_mutex_unlock(ca_mutex mutex);
  73
  74 /**
  75  * Free the mutex.
  76  *
  77  * @param  mutex  The mutex to be freed.
  78  *
  79  */
  80 bool ca_mutex_free(ca_mutex mutex);
  81
  82 /**
  83  * Creates new condition.
  84  *
  85  * @return  Reference to newly created ::ca_cond, otherwise NULL.
  86  *
  87  */
  88 ca_cond ca_cond_new(void);
  89
  90 /**
  91  * One of threads is woken up if multiple threads are waiting for cond.
  92  *
  93  * @param  cond  The condtion to be signaled.
  94  *
  95  */
  96 void ca_cond_signal(ca_cond cond);
  97
  98 /**
  99  * All of threads are woken up if multiple threads are waiting for cond.
 100  *
 101  * @param  cond  The condtion to be signaled.
 102  *
 103  */
 104 void ca_cond_broadcast(ca_cond cond);
 105
 106 /**
 107  * Waits until this thread woken up on cond.
 108  *
 109  * @param  cond  The condtion to be wait for to signal.
 110  * @param  mutex  The mutex which is currently locked from calling thread.
 111  *
 112  */
 113 void ca_cond_wait(ca_cond cond, ca_mutex mutex);
 114
 115 /**
 116  * Waits until this thread woken up on cond,
 117  * but not longer than the interval specified by microseconds.
 118  * The mutex is unlocked before falling asleep and locked again before resuming.
 119  * If microseconds is 0, ca_cond_wait_for() acts like ca_cond_wait().
 120  *
 121  * @param  cond  The condtion to be wait for to signal.
 122  * @param  mutex  The mutex which is currently locked from calling thread.
 123  * @param  microseconds  relative time for waiting, microseconds.
 124  *
 125  * @return ::CA_WAIT_SUCCESS if the condition was signaled,
 126  *         ::CA_WAIT_TIMEDOUT if wait period exceeded,
 127  *         ::CA_WAIT_INVAL for invalid parameters.
 128  *
 129  */
 130 CAWaitResult_t ca_cond_wait_for(ca_cond cond, ca_mutex mutex, uint64_t microseconds);
 131
 132 /**
 133  * Free the condition.
 134  *
 135  * @param  cond  The condition to be freed.
 136  *
 137  */
 138 void ca_cond_free(ca_cond cond);
 139
 140 #ifdef __cplusplus
 141 } /* extern "C" */
 142 #endif /* __cplusplus */
 143
 144 #endif /* CA_MUTEX_H_ */