RTI Connext DDS Micro  Version 2.4.6
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
osapi_timer.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_timer.h - Definition of Timer interface
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  * 22mar2012,tk Written
14  */
15 /*ce
16  * \file
17  * \brief Timer interface definition
18  *
19  * \details
20  * The Timer API provides a platform independent set of function to start
21  * timers and be notified when the timer expires. The concrete implementation
22  * of the platform dependent timer API are located in the platform specific
23  * files, such as vxTimer.c
24  *
25  * \defgroup OSAPI_TimerClass OSAPI Timer
26  * \ingroup OSAPIModule
27  *
28  * \details
29  */
30 #ifndef osapi_timer_h
31 #define osapi_timer_h
32 
33 
34 #ifndef osapi_dll_h
35 #include "osapi/osapi_dll.h"
36 #endif
37 #ifndef osapi_types_h
38 #include "osapi/osapi_types.h"
39 #endif
40 #ifndef osapi_thread_h
41 #include "osapi/osapi_thread.h"
42 #endif
43 #ifndef osapi_mutex_h
44 #include "osapi/osapi_mutex.h"
45 #endif
46 
47 #ifdef __cplusplus
48 extern "C"
49 {
50 #endif
51 
52 /*e \defgroup OSAPI_TimerClass OSAPI Timer
53  * \ingroup OSAPIModule
54 */
55 
56 /*e \file
57  \brief Timer API
58 */
59 
60 /*e \ingroup OSAPI_TimerClass
61  * \brief Create a periodic timer
62  */
63 #define OSAPI_TIMER_PERIODIC (0x1)
64 
65 /*e \ingroup OSAPI_TimerClass
66  * \brief Create a one-shot timer
67  */
68 #define OSAPI_TIMER_ONE_SHOT (0x0)
69 
70 /*e \ingroup OSAPI_TimerClass
71  * \brief Action taken by timer module when a timer callback returns.
72  */
73 typedef enum
74 {
75  OSAPI_TIMEOUT_OP_AUTOMATIC = 1,
76  OSAPI_TIMEOUT_OP_MANUAL
78 
79 /*e \ingroup OSAPI_TimerClass
80  * \brief User-data passed to timer-handler.
81  */
83 {
84  RTI_UINT32 count[2];
85  void *field[2];
86 };
87 
88 struct OSAPI_TimerEntry;
89 struct OSAPI_TimeoutHandle
90 {
91  /* In case an entry is re-used */
92  struct OSAPI_TimerEntry *_entry;
93 
94  /* In case an entry is re-used */
95  RTI_INT32 epoch;
96 };
97 
98 typedef struct OSAPI_TimeoutHandle OSAPI_TimeoutHandle_T;
99 
100 #define OSAPI_TimeoutHandle_INITIALIZER \
101 {\
102  NULL,\
103  -1\
104 }
105 
106 /*e \ingroup OSAPI_TimerClass
107  * \brief Timer properies
108  */
110 {
111  /*ci
112  * \brief The maximum number of timeouts
113  */
114  RTI_INT32 max_entries;
115 
116  /*ci
117  * \brief The maximum number slots in one round
118  */
119  RTI_INT32 max_slots;
120 
121  /*ci
122  * \brief The thread settings for the timer thread, if a thread is created
123  */
124  struct OSAPI_ThreadProperty thread;
125 };
126 
127 /*ci
128  * \brief Initializer for the \ref OSAPI_TimerProperty
129  */
130 #define OSAPI_TimerProperty_INITIALIZER \
131 {\
132  128,\
133  32,\
134  { /* OSAPI_ThreadProperty */ \
135  16*1024,\
136  OSAPI_THREAD_PRIORITY_NORMAL,\
137  OSAPI_THREAD_DEFAULT_OPTIONS,\
138  },\
139 }
140 
141 struct OSAPI_Timer;
142 typedef struct OSAPI_Timer *OSAPI_Timer_T;
143 
144 FUNCTION_MUST_TYPEDEF(
146 (*OSAPI_TimeoutFunction_T)(struct OSAPI_TimeoutUserData *user_data)
147 )
148 
149 typedef void
150 (*OSAPI_TimerTickHandlerFunction)(OSAPI_Timer_T timer);
151 
152 /*e \ingroup OSAPI_TimerClass
153  * \brief Create a Timer.
154  *
155  * \details Create a new Timer. A Timer can manage multiple timeouts.
156  *
157  * Example:
158  * \code
159  * OSAPI_Timer_t my_timer;
160  * struct OSAPI_TimerProperty timer_property = OSAPI_TimerProperty_INITIALIZER;
161  * timer = OSAPI_Timer_new(&timer_property);
162  * if (timer == NULL) {
163  * return error;
164  * }
165  * \endcode
166  *
167  * The created Timer should be deleted with \ref OSAPI_Timer_delete.
168  *
169  * @param[in] property Timer property.
170  * @param[in] mutex Shared mutex.
171  *
172  * @return New timer on success, NULL on failure
173  */
174 MUST_CHECK_RETURN OSAPIDllExport OSAPI_Timer_T
175 OSAPI_Timer_new(struct OSAPI_TimerProperty *property,struct OSAPI_Mutex *mutex);
176 
177 #ifndef RTI_CERT
178 /*e \ingroup OSAPI_TimerClass
179  * \brief Delete a Timer.
180  *
181  * \details Delete a previously created Timer. All timeouts are cancelled.
182  *
183  * Example:
184  * \code
185  * OSAPI_Timer_t my_timer;
186  *
187  * ......
188  *
189  * OSAPI_Timer_delete(my_timer);
190  * if (timer == NULL) {
191  * return error;
192  * }
193  * \endcode
194  *
195  * The created Timer should be deleted with \ref OSAPI_Timer_delete.
196  *
197  * @param [in] timer Timer.
198  *
199  * \return RTI_TRUE on success, RTI_FALSE on failure
200  *
201  * @mtsafety SAFE
202  */
203 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
204 OSAPI_Timer_delete(OSAPI_Timer_T timer);
205 #endif /* !RTI_CERT */
206 
207 /*e \ingroup OSAPI_TimerClass
208  * \brief Schedule a timeout.
209  *
210  * \details This function schedules a timeout with the specified period. The
211  * timeout can either be rescheduled automatically or a new timeout must
212  * be created.
213  *
214  * Example:
215  * \code
216  * OSAPI_Timer_t my_timer;
217  * OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
218  * RTI_BOOL result;
219  * struct OSAPI_TimerEntryUserData user_data;
220  *
221  * result = OSAPI_Timer_create_timeout(my_timer,
222  * &my_handle,
223  * 1000,0,
224  * OSAPI_TIMER_PERIODIC,
225  * &user_data);
226  *
227  * if (!result) {
228  * report error;
229  * }
230  *
231  * ......
232  *
233  * \endcode
234  *
235  * A timeout can cancelled with \ref OSAPI_Timer_delete_timeout or the timeout
236  * can be modified with \ref OSAPI_Timer_update_timeout.
237  *
238  * @param[in] timer Timer object. Cannot be NULL.
239  * @param[out] out_handle Reference to the timeout. Cannot be NULL.
240  * @param[in] timeout_sec The number of seconds before timeout
241  * @param[in] timeout_nsec Additional number of nanoseconds before timeout
242  * @param[in] flags Flags OSAPI_TIMER_PERIODIC or OSAPI_TIMER_ONE_SHOT
243  * @param[in] timeout_handler Function to call at timeout. Cannot be NULL.
244  * @param[in] user_data User data associated with the timeout. Can be NULL.
245  *
246  * \return RTI_TRUE on success, RTI_FALSE on failure
247  *
248  * @mtsafety SAFE
249  */
250 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
251 OSAPI_Timer_create_timeout(OSAPI_Timer_T timer,
252  OSAPI_TimeoutHandle_T *out_handle,
253  RTI_INT32 timeout_sec,
254  RTI_INT32 timeout_nsec,
255  RTI_INT32 flags,
256  OSAPI_TimeoutFunction_T timeout_handler,
257  struct OSAPI_TimeoutUserData *user_data);
258 
259 /*e \ingroup OSAPI_TimerClass
260  * \brief Reschedule a timeout.
261  *
262  * \details This function reschedules a previously scheduled timeout with
263  * the specified period.
264  *
265  * Example:
266  * \code
267  * OSAPI_Timer_t my_timer;
268  * OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
269  * RTI_BOOL result;
270  * struct OSAPI_TimerEntryUserData user_data;
271  *
272  * result = OSAPI_Timer_update_timeout(my_timer,
273  * &my_handle,
274  * 2000,0);
275  *
276  * if (!result) {
277  * report error;
278  * }
279  *
280  * ......
281  *
282  * \endcode
283  *
284  * @param [in] timer Timer object. Cannot be NULL.
285  * @param [out] out_handle Reference to the timeout. Cannot be NULL.
286  * @param[in] timeout_sec The number of seconds before timeout
287  * @param[in] timeout_nsec Additional number of nanoseconds before timeout
288  *
289  * \return RTI_TRUE on success, RTI_FALSE on failure
290  */
291 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
292 OSAPI_Timer_update_timeout(OSAPI_Timer_T timer,
293  OSAPI_TimeoutHandle_T *out_handle,
294  RTI_INT32 timeout_sec,
295  RTI_INT32 timeout_nsec);
296 
297 /*e \ingroup OSAPI_TimerClass
298  * \brief Stop a previously scheduled timeout
299  *
300  * \details This function stops a previously scheduled timeout.
301  *
302  * Example:
303  * \code
304  * OSAPI_Timer_t my_timer;
305  * OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
306  * RTI_BOOL result;
307  *
308  * ....
309  *
310  * result = OSAPI_Timer_stop_timer(my_timer,&my_handle);
311  *
312  * if (!result) {
313  * report error;
314  * }
315  *
316  * ......
317  *
318  * \endcode
319  *
320  * @param [in] timer Timer object. Cannot be NULL.
321  * @param [in] handle Reference to the timeout. Cannot be NULL.
322  *
323  * \return RTI_TRUE on success, RTI_FALSE on failure
324  *
325  * @mtsafety SAFE
326  */
327 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
328 OSAPI_Timer_delete_timeout(OSAPI_Timer_T timer, OSAPI_TimeoutHandle_T *handle);
329 
330 /*e \ingroup OSAPI_TimerClass
331  * \brief Get the user_data from a handle.
332  *
333  * Example:
334  * \code
335  * OSAPI_Timer_t my_timer;
336  * OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
337  * RTI_BOOL result;
338  * struct OSAPI_TimerEntryUserData user_data;
339  *
340  * ....
341  *
342  * result = OSAPITimeoutHandle_get_user_data(&user_data,&my_handle);
343  *
344  * if (!result) {
345  * report error;
346  * }
347  *
348  * ......
349  *
350  * \endcode
351  *
352  * @param [out] user_data User-data associated with handle. Cannot be NULL.
353  * @param [in] handle Timer handle.
354  *
355  * \return RTI_TRUE on success, RTI_FALSE on failure
356  */
357 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
359  OSAPI_TimeoutHandle_T *handle);
360 
361 #ifdef __cplusplus
362 } /* extern "C" */
363 #endif
364 
365 
366 #endif /* osapi_timer_h */

RTI Connext DDS Micro Version 2.4.6 Copyright © Mon Jan 25 2016 Real-Time Innovations, Inc