RTI Connext Micro  Version 2.4.4.0
 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  * 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 #ifndef RTI_CERT
80 /*e \ingroup OSAPI_SemaphoreClass
81  *
82  * \brief Delete a semaphore.
83  *
84  * \param [in] self Semaphore created with \ref OSAPI_Semaphore_new.
85  *
86  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Semaphore_new
87  */
88 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
89 OSAPI_Semaphore_delete(OSAPI_Semaphore_T *self);
90 #endif /* !RTI_CERT */
91 
92 /*e \ingroup OSAPI_SemaphoreClass
93  *
94  * \brief Take a semaphore.
95  *
96  * \param [in] self Semaphore previously created with \ref OSAPI_Semaphore_new.
97  *
98  * \param [in] timeout Timeout in ms. The `take` call will wait at most
99  * `timeout` ms before returning. If \ref
100  * OSAPI_SEMAPHORE_TIMEOUT_INFINITE is specified, the
101  * call will not return until the semaphore has a value of
102  * 1 or higher.
103  *
104  * \param [out] fail_reason This parameter is not used, but present for
105  * compatability reasons.
106  *
107  * \return RTI_TRUE on success, RTI_FALSE on failure.
108  *
109  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Semaphore_give
110  */
111 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
112 OSAPI_Semaphore_take(OSAPI_Semaphore_T *self,RTI_INT32 timeout,
113  RTI_INT32 *fail_reason);
114 
115 /*e \ingroup OSAPI_SemaphoreClass
116  *
117  * \brief Give a semaphore.
118  *
119  * \param [in] self Semaphore previously created with \ref OSAPI_Semaphore_new.
120  *
121  * \return RTI_TRUE on success, RTI_FALSE on failure.
122  *
123  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Semaphore_take
124  *
125  */
126 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
127 OSAPI_Semaphore_give(OSAPI_Semaphore_T *self);
128 
129 #ifdef __cplusplus
130 } /* extern "C" */
131 #endif
132 
133 
134 #endif /* osapi_semaphore_h */
RTI Connext Micro Version 2.4.4.0 Copyright © Thu Apr 30 2015 Real-Time Innovations, Inc