RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
osapi_semaphore.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_semaphore.h - Definition of semaphore interface
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 Semaphore interface definition
17  */
18 #ifndef osapi_semaphore_h
19 #define osapi_semaphore_h
20 
21 #ifndef osapi_dll_h
22 #include "osapi/osapi_dll.h"
23 #endif
24 #ifndef osapi_types_h
25 #include "osapi/osapi_types.h"
26 #endif
27 
28 #ifdef __cplusplus
29 extern "C"
30 {
31 #endif
32 
33 /*e \defgroup OSAPI_SemaphoreClass OSAPI Semaphore
34  \ingroup OSAPIModule
35 
36  \brief Abstract Semaphore API.
37  */
38 
39 /*e
40  * Infinite timeout
41  */
42 #define OSAPI_SEMAPHORE_TIMEOUT_INFINITE -1
43 
44 /*e
45  * Semaphore ok
46  */
47 #define OSAPI_SEMAPHORE_RESULT_OK 0
48 
49 /*e
50  * Semaphore timed out
51  */
52 #define OSAPI_SEMAPHORE_RESULT_TIMEOUT 1
53 
54 /*e
55  * Semaphore error
56  */
57 #define OSAPI_SEMAPHORE_RESULT_ERROR 2
58 
59 struct OSAPI_Semaphore;
60 
61 /*e \ingroup OSAPI_SemaphoreClass
62  *
63  * \brief Abstract semaphore object.
64  */
65 typedef struct OSAPI_Semaphore OSAPI_Semaphore_T;
66 
67 /*e \ingroup OSAPI_SemaphoreClass
68  *
69  * \brief Create a semaphore.
70  *
71  * \return Pointer to a semaphore with a value of 1 on success, NULL on failure.
72  *
73  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Semaphore_delete
74  *
75  */
76 MUST_CHECK_RETURN OSAPIDllExport OSAPI_Semaphore_T*
77 OSAPI_Semaphore_new(void);
78 
79 /*e \ingroup OSAPI_SemaphoreClass
80  *
81  * \brief Delete a semaphore.
82  *
83  * \param [in] self Semaphore created with \ref OSAPI_Semaphore_new.
84  *
85  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Semaphore_new
86  */
87 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
88 OSAPI_Semaphore_delete(OSAPI_Semaphore_T *self);
89 
90 /*e \ingroup OSAPI_SemaphoreClass
91  *
92  * \brief Take a semaphore.
93  *
94  * \param [in] self Semaphore previously created with \ref OSAPI_Semaphore_new.
95  *
96  * \param [in] timeout Timeout in ms. The `take` call will wait at most
97  * `timeout` ms before returning. If \ref
98  * OSAPI_SEMAPHORE_TIMEOUT_INFINITE is specified, the
99  * call will not return until the semaphore has a value of
100  * 1 or higher.
101  *
102  * \param [out] fail_reason This parameter is not used, but present for
103  * compatability reasons.
104  *
105  * \return RTI_TRUE on success, RTI_FALSE on failure.
106  *
107  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Semaphore_give
108  */
109 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
110 OSAPI_Semaphore_take(OSAPI_Semaphore_T *self,RTI_INT32 timeout,
111  RTI_INT32 *fail_reason);
112 
113 /*e \ingroup OSAPI_SemaphoreClass
114  *
115  * \brief Give a semaphore.
116  *
117  * \param [in] self Semaphore previously created with \ref OSAPI_Semaphore_new.
118  *
119  * \return RTI_TRUE on success, RTI_FALSE on failure.
120  *
121  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Semaphore_take
122  *
123  */
124 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
125 OSAPI_Semaphore_give(OSAPI_Semaphore_T *self);
126 
127 #ifdef __cplusplus
128 } /* extern "C" */
129 #endif
130 
131 
132 #endif /* osapi_semaphore_h */
RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc