1 /* ****************************************************************
3 * Copyright 2014 Samsung Electronics All Rights Reserved.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 ******************************************************************/
24 * This file provides APIs related to mutex and semaphores.
38 #endif /* __cplusplus */
40 typedef struct oc_mutex_internal *oc_mutex;
41 typedef struct oc_cond_internal *oc_cond;
42 typedef struct oc_thread_internal *oc_thread;
45 * Enums for oc_cond_wait_for return values.
49 OC_WAIT_SUCCESS = 0, /**< Condition Signal. */
50 OC_WAIT_INVAL = -1, /**< Invalid Condition. */
51 OC_WAIT_TIMEDOUT = -2 /**< Condition Timed Out. */
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
67 * Allocates, and starts a new thread
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
79 OCThreadResult_t oc_thread_new(oc_thread *t, void *(*start_routine)(void *), void *arg);
81 OCThreadResult_t oc_thread_new(oc_thread *t, void *(*start_routine)(void *), void *arg,
82 const char *task_name, int stack_size);
86 * Frees a thread previously allocated with oc_thread_new()
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
94 OCThreadResult_t oc_thread_free(oc_thread t);
97 * Block until a thread's execution has been completed
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
105 OCThreadResult_t oc_thread_wait(oc_thread t);
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
116 OCThreadResult_t oc_thread_detach(oc_thread t);
120 * Cancel the thread without block
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
128 OCThreadResult_t oc_thread_cancel(oc_thread t);
134 * @return Reference to newly created mutex, otherwise NULL.
137 oc_mutex oc_mutex_new(void);
142 * @param mutex The mutex to be locked.
145 void oc_mutex_lock(oc_mutex mutex);
150 * @param mutex The mutex to be unlocked.
153 void oc_mutex_unlock(oc_mutex mutex);
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
164 bool oc_mutex_free(oc_mutex mutex);
167 * Creates new condition.
169 * @return Reference to newly created oc_cond, otherwise NULL.
172 oc_cond oc_cond_new(void);
175 * One of threads is woken up if multiple threads are waiting for cond.
177 * @param cond The condtion to be signaled.
180 void oc_cond_signal(oc_cond cond);
183 * All of threads are woken up if multiple threads are waiting for cond.
185 * @param cond The condtion to be signaled.
188 void oc_cond_broadcast(oc_cond cond);
191 * Waits until this thread woken up on cond.
193 * @param cond The condtion to be wait for to signal.
194 * @param mutex The mutex which is currently locked from calling thread.
197 void oc_cond_wait(oc_cond cond, oc_mutex mutex);
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().
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.
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.
214 OCWaitResult_t oc_cond_wait_for(oc_cond cond, oc_mutex mutex, uint64_t microseconds);
217 * Free the condition.
219 * @param cond The condition to be freed.
222 void oc_cond_free(oc_cond cond);
226 #endif /* __cplusplus */
228 #endif /* OC_THREAD_H_ */