RTI Connext DDS Micro  Version 2.4.10
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
osapi_thread.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_thread.h - Definition of System API
3  *
4  * Copyright 2012-2015 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 /* these are #defined so users can pass in any int they want for priority as well
39  * i.e., OS-native thread priorities
40  */
41 #define OSAPI_THREAD_PRIORITY_LOW -1
42 #define OSAPI_THREAD_PRIORITY_BELOW_NORMAL -2
43 #define OSAPI_THREAD_PRIORITY_NORMAL -3
44 #define OSAPI_THREAD_PRIORITY_ABOVE_NORMAL -4
45 #define OSAPI_THREAD_PRIORITY_HIGH -5
46 
47 #define OSAPI_THREAD_USE_OSDEFAULT_STACKSIZE 0
48 
49 /*e \ingroup OSAPI_ThreadClass
50  * Thread options
51  */
52 typedef RTI_UINT32 OSAPI_ThreadOptions;
53 
54 /*e \ingroup OSAPI_ThreadClass
55  Use only the default options the OS gives you.
56 */
57 #define OSAPI_THREAD_DEFAULT_OPTIONS 0x00
58 /*e \ingroup OSAPI_ThreadClass
59  Support floating point.
60 */
61 #define OSAPI_THREAD_FLOATING_POINT 0x01
62 /*e \ingroup OSAPI_ThreadClass
63  Support standard I/O.
64 */
65 #define OSAPI_THREAD_STDIO 0x02
66 /*e \ingroup OSAPI_ThreadClass
67  Run in real-time priority mode.
68 */
69 #define OSAPI_THREAD_REALTIME_PRIORITY 0x08
70 /*e \ingroup OSAPI_ThreadClass
71  Insist on the specified priority and fail if the OS doesn't like it.
72 */
73 #define OSAPI_THREAD_PRIORITY_ENFORCE 0x10
74 /*e \ingroup OSAPI_ThreadClass
75  Support the ability to asynchronously cancel the thread.
76 */
77 #define OSAPI_THREAD_CANCEL_ASYNCHRONOUS 0x20
78 
79 /*e \ingroup OSAPI_ThreadClass
80  *
81  */
82 struct OSAPI_ThreadProperty
83 {
84  /*e Hint on required stack-size */
85  RTI_UINT32 stack_size;
86 
87  /*e Hint on required priority */
88  RTI_INT32 priority;
89 
90  /*e Hint on thread priorites if support by the OS */
91  OSAPI_ThreadOptions options;
92 };
93 
94 /*e \ingroup OSAPI_ThreadClass
95  * Initializer for thread properties
96  */
97 #define OSAPI_THREAD_PROPERTY_DEFAULT \
98 { \
99  OSAPI_THREAD_USE_OSDEFAULT_STACKSIZE, \
100  OSAPI_THREAD_PRIORITY_NORMAL, \
101  OSAPI_THREAD_DEFAULT_OPTIONS \
102 }
103 
104 #define OSAPI_ThreadProperty_INITIALIZER OSAPI_THREAD_PROPERTY_DEFAULT
105 /*e
106  * \ingroup OSAPI_ThreadClass
107  * \brief Thread info
108  *
109  */
111 {
112  /*e Stop executing thread */
113  RTI_BOOL stop_thread;
114 
115  /*e Whether or not the created thread is preemptive */
116  RTI_BOOL is_premptive;
117 
118  /*e Parameter passed by thread creator. Passed to thread. */
119  void *user_data;
120 };
121 
122 /*e \ingroup OSAPI_ThreadClass
123  *
124  * \brief Thread task signature.
125  *
126  * \param[in] thread_info Thread information structure
127  *
128  * \return RTI_TRUE on successful execution, RTI_FALSE on failure.
129  */
130 FUNCTION_SHOULD_TYPEDEF(
131 RTI_BOOL
132 (*OSAPI_ThreadRoutine)(struct OSAPI_ThreadInfo *thread_info)
133 )
134 
135 /*e \ingroup OSAPI_ThreadClass
136  *
137  * \brief Abstract thread class.
138  */
139 struct OSAPI_Thread;
140 
141 
142 /*e \ingroup OSAPI_ThreadClass
143  *
144  * \brief Wakeup user-thread
145  *
146  * \details
147  *
148  * If a user-defined thread function is blocking, e.g. waiting for
149  * data, and the user wants to delete the thread, it is necessary to
150  * unblock the user-thread. The user must provide a function which can
151  * unblock a thread. This function calls the wake up function to wake up a
152  * blocked user thread.
153  *
154  * \param [in] self OSAPI_Thread to wakeup
155  *
156  * \return RTI_TRUE on success, RTI_FALSE on failure.
157  *
158  * \sa \ref OSAPI_Thread_start
159  */
160 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
161 OSAPI_Thread_wakeup(struct OSAPI_Thread *self);
162 
163 /*e \ingroup OSAPI_ThreadClass
164  *
165  * \brief Start a specific thread.
166  *
167  * \param [in] me Thread to wake up
168  *
169  * \return RTI_TRUE on success, RTI_FALSE on failure.
170  *
171  * \sa \ref OSAPI_Thread_create
172  */
173 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
174 OSAPI_Thread_start(struct OSAPI_Thread *me);
175 
176 
177 /*e \ingroup OSAPI_ThreadClass
178  * \brief Destroy a specific thread.
179  *
180  * \param [in] self Thread.
181  *
182  * \return RTI_TRUE on success, RTI_FALSE on failure.
183  *
184  * \sa \ref OSAPI_Thread_create
185  */
186 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
187 OSAPI_Thread_destroy(struct OSAPI_Thread *self);
188 
189 /*e \ingroup OSAPI_ThreadClass
190  * \brief Suspend a thread for a specified amount of time.
191  *
192  * \param [in] ms Sleep time.
193  *
194  */
195 OSAPIDllExport void
196 OSAPI_Thread_sleep(RTI_UINT32 ms);
197 
198 /*e \ingroup OSAPI_ThreadClass
199  *
200  * \brief Create a thread.
201  *
202  * \param [in] name The name of the thread.
203  *
204  * \param [in] properties Thread properties. These properties are hints.
205  *
206  * \param [in] user_routine Thread task. The thread task cannot assume that
207  * it can block; thus it must be written such that
208  * it can be called repeatedly.
209  *
210  * \param [in] user_data Parameters passed to the thread task.
211  *
212  * \param [in] wakeup_routine Routine to wake up a thread, called to delete
213  * a thread.
214  *
215  * \return Handle to stopped thread on success, NULL on failure.
216  *
217  * \sa \ref OSAPI_Thread_destroy
218  */
219 MUST_CHECK_RETURN OSAPIDllExport struct OSAPI_Thread*
220 OSAPI_Thread_create(const char *name,
221  const struct OSAPI_ThreadProperty *properties,
222  OSAPI_ThreadRoutine user_routine,
223  void *user_data,
224  OSAPI_ThreadRoutine wakeup_routine);
225 
226 
227 /*e \ingroup OSAPI_ThreadClass
228  *
229  * \brief Return thread ID.
230  *
231  * \return thread ID of the calling thread.
232  *
233  * \sa \ref OSAPI_Thread_create
234  */
235 OSAPIDllExport OSAPI_ThreadId
236 OSAPI_Thread_self(void);
237 
238 #ifdef __cplusplus
239 } /* extern "C" */
240 #endif
241 
242 
243 #endif /* osapi_thread_h */

RTI Connext DDS Micro Version 2.4.10 Copyright © Fri Jun 30 2017 Real-Time Innovations, Inc