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