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 } OCThreadResult_t;
  64
  65 /**
  66  * Allocates, and starts a new thread
  67  *
  68  * @param[out] t  The thread that will refer to a newly allocated, and started thread
  69  * @param[in] start_routine The function that will execute in a new thread
  70  * @param[in] arg The information passed to the start_routine
  71  * @return OCThreadResult_t An enumeration of possible outcomes
  72  * @retval OC_THREAD_SUCCESS If a thread was successfully allocated and started.
  73  * @retval OC_THREAD_ALLOCATION_FAILURE If a thread was unable to be allocated
  74  * @retval OC_THREAD_CREATE_FAILURE If a thread was unable to be started
  75  *
  76  */
  77 #ifndef __TIZENRT__
  78 OCThreadResult_t oc_thread_new(oc_thread *t, void *(*start_routine)(void *), void *arg);
  79 #else
  80 OCThreadResult_t oc_thread_new(oc_thread *t, void *(*start_routine)(void *), void *arg,
  81                                const char *task_name, int stack_size);
  82 #endif
  83
  84 /**
  85  * Frees a thread previously allocated with oc_thread_new()
  86  *
  87  * @param[in] t The thread to be unallocated
  88  * @return OCThreadResult_t An enumeration of possible outcomes
  89  * @retval OC_THREAD_SUCCESS If a thread was successfully unallocated
  90  * @retval OC_THREAD_INVALID_PARAMETER If param t is NULL
  91  *
  92  */
  93 OCThreadResult_t oc_thread_free(oc_thread t);
  94
  95 /**
  96  * Block until a thread's execution has been completed
  97  *
  98  * @param[in] t The thread to be waited on
  99  * @return OCThreadResult_t An enumeration of possible outcomes
 100  * @retval OC_THREAD_SUCCESS If the thread successfully completed execution
 101  * @retval OC_THREAD_WAIT_FAILURE If a problem occured while waiting for execution of the thread to complete
 102  *
 103  */
 104 OCThreadResult_t oc_thread_wait(oc_thread t);
 105
 106 #ifdef __TIZEN__
 107 /**
 108  * Cancel the thread without block
 109  *
 110  * @param[in] t The thread to be canceled on
 111  * @return OCThreadResult_t An enumeration of possible outcomes
 112  * @retval OC_THREAD_SUCCESS If the thread successfully completed execution
 113  * @retval OC_THREAD_CANCEL_FAILURE If a problem occured while canceling
 114  *
 115  */
 116 OCThreadResult_t oc_thread_cancel(oc_thread t);
 117 #endif
 118
 119 /**
 120  * Creates new mutex.
 121  *
 122  * @return  Reference to newly created mutex, otherwise NULL.
 123  *
 124  */
 125 oc_mutex oc_mutex_new(void);
 126
 127 /**
 128  * Lock the mutex.
 129  *
 130  * @param  mutex  The mutex to be locked.
 131  *
 132  */
 133 void oc_mutex_lock(oc_mutex mutex);
 134
 135 /**
 136  * Unlock the mutex.
 137  *
 138  * @param  mutex  The mutex to be unlocked.
 139  *
 140  */
 141 void oc_mutex_unlock(oc_mutex mutex);
 142
 143 /**
 144  * Free the mutex.
 145  *
 146  * @param  mutex  The mutex to be freed.
 147  * @return bool to indicate success or failure
 148  * @retval true if mutex was freed successfully
 149  * @retval false if mutex parameter is invalid
 150  *
 151  */
 152 bool oc_mutex_free(oc_mutex mutex);
 153
 154 /**
 155  * Creates new condition.
 156  *
 157  * @return  Reference to newly created oc_cond, otherwise NULL.
 158  *
 159  */
 160 oc_cond oc_cond_new(void);
 161
 162 /**
 163  * One of threads is woken up if multiple threads are waiting for cond.
 164  *
 165  * @param  cond  The condtion to be signaled.
 166  *
 167  */
 168 void oc_cond_signal(oc_cond cond);
 169
 170 /**
 171  * All of threads are woken up if multiple threads are waiting for cond.
 172  *
 173  * @param  cond  The condtion to be signaled.
 174  *
 175  */
 176 void oc_cond_broadcast(oc_cond cond);
 177
 178 /**
 179  * Waits until this thread woken up on cond.
 180  *
 181  * @param  cond  The condtion to be wait for to signal.
 182  * @param  mutex  The mutex which is currently locked from calling thread.
 183  *
 184  */
 185 void oc_cond_wait(oc_cond cond, oc_mutex mutex);
 186
 187 /**
 188  * Waits until this thread woken up on cond,
 189  * but not longer than the interval specified by microseconds.
 190  * The mutex is unlocked before falling asleep and locked again before resuming.
 191  * If microseconds is 0, oc_cond_wait_for() acts like oc_cond_wait().
 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  * @param  microseconds  relative time for waiting, microseconds.
 196  *
 197  * @return OC_WAIT_SUCCESS if the condition was signaled,
 198  *         OC_WAIT_TIMEDOUT if wait period exceeded,
 199  *         OC_WAIT_INVAL for invalid parameters.
 200  *
 201  */
 202 OCWaitResult_t oc_cond_wait_for(oc_cond cond, oc_mutex mutex, uint64_t microseconds);
 203
 204 /**
 205  * Free the condition.
 206  *
 207  * @param  cond  The condition to be freed.
 208  *
 209  */
 210 void oc_cond_free(oc_cond cond);
 211
 212 #ifdef __cplusplus
 213 } /* extern "C" */
 214 #endif /* __cplusplus */
 215
 216 #endif /* OC_THREAD_H_ */