RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
osapi_thread.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_thread.h - Definition of System API
3  *
4  * Copyright 2012-2014 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 12mar2012,tk Written
14  */
15 /*e \file
16  * \brief Thread interface definition
17  */
18 #ifndef osapi_thread_h
19 #define osapi_thread_h
20 
21 #include "osapi/osapi_config.h"
22 #ifndef osapi_dll_h
23 #include "osapi/osapi_dll.h"
24 #endif
25 #ifndef osapi_types_h
26 #include "osapi/osapi_types.h"
27 #endif
28 
29 #ifdef __cplusplus
30 extern "C"
31 {
32 #endif
33 
34 /*e \defgroup OSAPI_ThreadClass OSAPI Thread
35  * \ingroup OSAPIModule
36 */
37 
38 /*e \ingroup OSAPI_ThreadClass
39 
40  \brief Abstract Thread API.
41 */
42 #ifdef INCLUDE_POSIX
43 #include <pthread.h>
44 #define OSAPI_ThreadHandle pthread_t
45 #define OSAPI_ThreadId pthread_t
46 #elif OSAPI_PLATFORM == OSAPI_PLATFORM_WINDOWS
47 #include <windows.h>
48 #include <process.h>
49 #define OSAPI_ThreadHandle HANDLE
50 #define OSAPI_ThreadId HANDLE
51 #elif OSAPI_PLATFORM == OSAPI_PLATFORM_STOS
52 #define OSAPI_ThreadHandle RTI_INT32
53 #define OSAPI_ThreadId RTI_INT32
54 #elif OSAPI_PLATFORM == OSAPI_PLATFORM_STELLARIS
55 #define OSAPI_ThreadHandle RTI_INT32
56 #define OSAPI_ThreadId RTI_INT32
57 #elif OSAPI_PLATFORM == OSAPI_PLATFORM_FREERTOS
58 #ifndef INC_FREERTOS_H
59 #include "FreeRTOS.h"
60 #endif
61 #ifndef TASK_H
62 #include "task.h"
63 #endif
64 #define OSAPI_ThreadHandle xTaskHandle
65 #define OSAPI_ThreadId xTaskHandle
66 #elif OSAPI_PLATFORM == OSAPI_PLATFORM_VXWORKS
67 #define OSAPI_ThreadId int
68 #define OSAPI_ThreadHandle int
69 #else
70 #error "thread handle not ported"
71 #endif
72 
73 /* these are #defined so users can pass in any int they want for priority as well
74  * i.e., OS-native thread priorities
75  */
76 #define OSAPI_THREAD_PRIORITY_LOW -1
77 #define OSAPI_THREAD_PRIORITY_BELOW_NORMAL -2
78 #define OSAPI_THREAD_PRIORITY_NORMAL -3
79 #define OSAPI_THREAD_PRIORITY_ABOVE_NORMAL -4
80 #define OSAPI_THREAD_PRIORITY_HIGH -5
81 
82 #define OSAPI_THREAD_USE_OSDEFAULT_STACKSIZE 0
83 
84 /*e \ingroup OSAPI_ThreadClass
85  * Thread options
86  */
87 typedef RTI_UINT32 OSAPI_ThreadOptions;
88 
89 /*e \ingroup OSAPI_ThreadClass
90  Use only the default options the OS gives you.
91 */
92 #define OSAPI_THREAD_DEFAULT_OPTIONS 0x00
93 /*e \ingroup OSAPI_ThreadClass
94  Support floating point.
95 */
96 #define OSAPI_THREAD_FLOATING_POINT 0x01
97 /*e \ingroup OSAPI_ThreadClass
98  Support standard I/O.
99 */
100 #define OSAPI_THREAD_STDIO 0x02
101 /*e \ingroup OSAPI_ThreadClass
102  Run in real-time priority mode.
103 */
104 #define OSAPI_THREAD_REALTIME_PRIORITY 0x08
105 /*e \ingroup OSAPI_ThreadClass
106  Insist on the specified priority and fail if the OS doesn't like it.
107 */
108 #define OSAPI_THREAD_PRIORITY_ENFORCE 0x10
109 /*e \ingroup OSAPI_ThreadClass
110  Support the ability to asynchronously cancel the thread.
111 */
112 #define OSAPI_THREAD_CANCEL_ASYNCHRONOUS 0x20
113 
114 /*e \ingroup OSAPI_ThreadClass
115  *
116  */
117 struct OSAPI_ThreadProperty
118 {
119  /*e Hint on required stack-size */
120  RTI_UINT32 stack_size;
121 
122  /*e Hint on required priority */
123  RTI_INT32 priority;
124 
125  OSAPI_ThreadOptions options;
126 };
127 
128 /*e \ingroup OSAPI_ThreadClass
129  * Initializer for thread properties
130  */
131 #define OSAPI_THREAD_PROPERTY_DEFAULT \
132 { \
133  OSAPI_THREAD_USE_OSDEFAULT_STACKSIZE, \
134  OSAPI_THREAD_PRIORITY_NORMAL, \
135  OSAPI_THREAD_DEFAULT_OPTIONS \
136 }
137 
138 #define OSAPI_ThreadProperty_INITIALIZER OSAPI_THREAD_PROPERTY_DEFAULT
139 /*e
140  * \ingroup OSAPI_ThreadClass
141  * \brief Thread info
142  *
143  */
145 {
146  /*e Stop executing thread */
148 
149  /*e Whether or not the created thread is preemptive */
151 
152  /*e Parameter passed by thread creator. Passed to thread. */
153  void *user_data;
154 };
155 
156 /*e \ingroup OSAPI_ThreadClass
157  *
158  * \brief Thread task signature.
159  *
160  * \param[in] thread_info Thread information structure
161  *
162  * \return RTI_TRUE on successful execution, RTI_FALSE on failure.
163  */
164 FUNCTION_SHOULD_TYPEDEF(
165 RTI_BOOL
166 (*OSAPI_ThreadRoutine)(struct OSAPI_ThreadInfo *thread_info)
167 )
168 
169 /*e \ingroup OSAPI_ThreadClass
170  *
171  * \brief Abstract thread class.
172  */
173 struct OSAPI_Thread;
174 
175 
176 /*e \ingroup OSAPI_ThreadClass
177  *
178  * \brief Wakeup user-thread
179  *
180  * \details
181  *
182  * If a user-defined thread function is blocking, e.g. waiting for
183  * data, and the user wants to delete the thread, it is necessary to
184  * unblock the user-thread. The user must provide a function which can
185  * unblock a thread. This function call the wakup function to wakeup a
186  * block user thread.
187  *
188  * \param [in] self OSAPI_Thread to wakeup
189  *
190  * \return RTI_TRUE on succsess, RTI_FALSE on failure.
191  *
192  * \sa \ref OSAPI_Thread_start
193  */
194 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
195 OSAPI_Thread_wakeup(struct OSAPI_Thread *self);
196 
197 /*e \ingroup OSAPI_ThreadClass
198  *
199  * \brief Start a specific thread.
200  *
201  * \param [in] me Thread to wakeup
202  *
203  * \return RTI_TRUE on success, RTI_FALSE on failure.
204  *
205  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Thread_create
206  */
207 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
208 OSAPI_Thread_start(struct OSAPI_Thread *me);
209 
210 
211 /*e \ingroup OSAPI_ThreadClass
212  *
213  * \brief Destroy a specific thread.
214  * \param [in] self Thread.
215  * \return RTI_TRUE on success, RTI_FALSE on failure.
216  *
217  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Thread_create
218  */
219 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
220 OSAPI_Thread_destroy(struct OSAPI_Thread *self);
221 
222 /*e \ingroup OSAPI_ThreadClass
223  *
224  * \brief Suspend a thread for a specified amount of time.
225  *
226  * \param [in] ms Sleep time.
227  *
228  * \sa \ref OSAPIPortingIntroClass
229  */
230 OSAPIDllExport void
231 OSAPI_Thread_sleep(RTI_UINT32 ms);
232 
233 /*e \ingroup OSAPI_ThreadClass
234  *
235  * \brief Create a thread.
236  *
237  * \param [in] name The name of the thread.
238  *
239  * \param [in] properties Thread properties. These properties are hints.
240  *
241  * \param [in] user_routine Thread task. The thread task cannot assume that
242  * it can block; thus it must be written such that
243  * it can be called repeatedly.
244  *
245  * \param [in] user_data Parameters passed to the thread task.
246  *
247  * \param [in] wakeup_routine Routine to wakeup a thread, called to delete
248  * a thread.
249  *
250  * \return Handle to stopped thread on success, NULL on failure.
251  *
252  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Thread_destroy
253  */
254 MUST_CHECK_RETURN OSAPIDllExport struct OSAPI_Thread*
255 OSAPI_Thread_create(const char *name,
256  const struct OSAPI_ThreadProperty *properties,
257  OSAPI_ThreadRoutine user_routine,
258  void *user_data,
259  OSAPI_ThreadRoutine wakeup_routine);
260 
261 
262 /*e \ingroup OSAPI_ThreadClass
263  *
264  * \brief Return thread ID.
265  *
266  * \return thread ID of the calling thread.
267  *
268  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Thread_create
269  */
270 OSAPIDllExport OSAPI_ThreadId
271 OSAPI_Thread_self(void);
272 
273 #ifdef __cplusplus
274 } /* extern "C" */
275 #endif
276 
277 
278 #endif /* osapi_thread_h */

RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc