resource/c_common/octhread/include/octhread.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 OC_THREAD_H_
  28 #define OC_THREAD_H_
  29
  30 #include <stdbool.h>
  31 #include <stdlib.h>
  32 #include <stdint.h>
  33
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #endif /* __cplusplus */
  39
  40 typedef struct oc_mutex_internal *oc_mutex;
  41 typedef struct oc_cond_internal *oc_cond;
  42 typedef struct oc_thread_internal *oc_thread;
  43
  44 /**
  45  * Enums for oc_cond_wait_for return values.
  46  */
  47 typedef enum
  48 {
  49    OC_WAIT_SUCCESS = 0,    /**< Condition Signal. */
  50    OC_WAIT_INVAL = -1,     /**< Invalid Condition. */
  51    OC_WAIT_TIMEDOUT = -2   /**< Condition Timed Out. */
  52 } OCWaitResult_t;
  53
  54 typedef enum
  55 {
  56     OC_THREAD_SUCCESS = 0,
  57     OC_THREAD_ALLOCATION_FAILURE = 1,
  58     OC_THREAD_CREATE_FAILURE = 2,
  59     OC_THREAD_INVALID = 3,
  60     OC_THREAD_WAIT_FAILURE = 4,
  61     OC_THREAD_INVALID_PARAMETER = 5,
  62     OC_THREAD_CANCEL_FAILURE = 6,
  63     OC_THREAD_DETACH_FAILURE = 7
  64 } OCThreadResult_t;
  65
  66 /**
  67  * Allocates, and starts a new thread
  68  *
  69  * @param[out] t  The thread that will refer to a newly allocated, and started thread
  70  * @param[in] start_routine The function that will execute in a new thread
  71  * @param[in] arg The information passed to the start_routine
  72  * @return OCThreadResult_t An enumeration of possible outcomes
  73  * @retval OC_THREAD_SUCCESS If a thread was successfully allocated and started.
  74  * @retval OC_THREAD_ALLOCATION_FAILURE If a thread was unable to be allocated
  75  * @retval OC_THREAD_CREATE_FAILURE If a thread was unable to be started
  76  *
  77  */
  78 #ifndef __TIZENRT__
  79 OCThreadResult_t oc_thread_new(oc_thread *t, void *(*start_routine)(void *), void *arg);
  80 #else
  81 OCThreadResult_t oc_thread_new(oc_thread *t, void *(*start_routine)(void *), void *arg,
  82                                const char *task_name, int stack_size);
  83 #endif
  84
  85 /**
  86  * Frees a thread previously allocated with oc_thread_new()
  87  *
  88  * @param[in] t The thread to be unallocated
  89  * @return OCThreadResult_t An enumeration of possible outcomes
  90  * @retval OC_THREAD_SUCCESS If a thread was successfully unallocated
  91  * @retval OC_THREAD_INVALID_PARAMETER If param t is NULL
  92  *
  93  */
  94 OCThreadResult_t oc_thread_free(oc_thread t);
  95
  96 /**
  97  * Block until a thread's execution has been completed
  98  *
  99  * @param[in] t The thread to be waited on
 100  * @return OCThreadResult_t An enumeration of possible outcomes
 101  * @retval OC_THREAD_SUCCESS If the thread successfully completed execution
 102  * @retval OC_THREAD_WAIT_FAILURE If a problem occured while waiting for execution of the thread to complete
 103  *
 104  */
 105 OCThreadResult_t oc_thread_wait(oc_thread t);
 106
 107 /**
 108  * Detach the thread
 109  *
 110  * @param[in] t The thread to be detached
 111  * @return OCThreadResult_t An enumeration of possible outcomes
 112  * @retval OC_THREAD_SUCCESS If the thread successfully detached
 113  * @retval OC_THREAD_DETACH_FAILURE If a problem occured while detaching
 114  *
 115  */
 116 OCThreadResult_t oc_thread_detach(oc_thread t);
 117
 118 #ifdef __TIZEN__
 119 /**
 120  * Cancel the thread without block
 121  *
 122  * @param[in] t The thread to be canceled on
 123  * @return OCThreadResult_t An enumeration of possible outcomes
 124  * @retval OC_THREAD_SUCCESS If the thread successfully completed execution
 125  * @retval OC_THREAD_CANCEL_FAILURE If a problem occured while canceling
 126  *
 127  */
 128 OCThreadResult_t oc_thread_cancel(oc_thread t);
 129 #endif
 130
 131 /**
 132  * Creates new mutex.
 133  *
 134  * @return  Reference to newly created mutex, otherwise NULL.
 135  *
 136  */
 137 oc_mutex oc_mutex_new(void);
 138
 139 /**
 140  * Lock the mutex.
 141  *
 142  * @param  mutex  The mutex to be locked.
 143  *
 144  */
 145 void oc_mutex_lock(oc_mutex mutex);
 146
 147 /**
 148  * Unlock the mutex.
 149  *
 150  * @param  mutex  The mutex to be unlocked.
 151  *
 152  */
 153 void oc_mutex_unlock(oc_mutex mutex);
 154
 155 /**
 156  * Free the mutex.
 157  *
 158  * @param  mutex  The mutex to be freed.
 159  * @return bool to indicate success or failure
 160  * @retval true if mutex was freed successfully
 161  * @retval false if mutex parameter is invalid
 162  *
 163  */
 164 bool oc_mutex_free(oc_mutex mutex);
 165
 166 /**
 167  * Creates new condition.
 168  *
 169  * @return  Reference to newly created oc_cond, otherwise NULL.
 170  *
 171  */
 172 oc_cond oc_cond_new(void);
 173
 174 /**
 175  * One of threads is woken up if multiple threads are waiting for cond.
 176  *
 177  * @param  cond  The condtion to be signaled.
 178  *
 179  */
 180 void oc_cond_signal(oc_cond cond);
 181
 182 /**
 183  * All of threads are woken up if multiple threads are waiting for cond.
 184  *
 185  * @param  cond  The condtion to be signaled.
 186  *
 187  */
 188 void oc_cond_broadcast(oc_cond cond);
 189
 190 /**
 191  * Waits until this thread woken up on cond.
 192  *
 193  * @param  cond  The condtion to be wait for to signal.
 194  * @param  mutex  The mutex which is currently locked from calling thread.
 195  *
 196  */
 197 void oc_cond_wait(oc_cond cond, oc_mutex mutex);
 198
 199 /**
 200  * Waits until this thread woken up on cond,
 201  * but not longer than the interval specified by microseconds.
 202  * The mutex is unlocked before falling asleep and locked again before resuming.
 203  * If microseconds is 0, oc_cond_wait_for() acts like oc_cond_wait().
 204  *
 205  * @param  cond  The condtion to be wait for to signal.
 206  * @param  mutex  The mutex which is currently locked from calling thread.
 207  * @param  microseconds  relative time for waiting, microseconds.
 208  *
 209  * @return OC_WAIT_SUCCESS if the condition was signaled,
 210  *         OC_WAIT_TIMEDOUT if wait period exceeded,
 211  *         OC_WAIT_INVAL for invalid parameters.
 212  *
 213  */
 214 OCWaitResult_t oc_cond_wait_for(oc_cond cond, oc_mutex mutex, uint64_t microseconds);
 215
 216 /**
 217  * Free the condition.
 218  *
 219  * @param  cond  The condition to be freed.
 220  *
 221  */
 222 void oc_cond_free(oc_cond cond);
 223
 224 #ifdef __cplusplus
 225 } /* extern "C" */
 226 #endif /* __cplusplus */
 227
 228 #endif /* OC_THREAD_H_ */