RTI Connext Micro  Version 2.4.4.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
osapi_mutex.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_mutex.h - Definition of mutex 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 /*ce
16  * \file
17  * \brief Definition of mutex interface
18  */
19 #ifndef osapi_mutex_h
20 #define osapi_mutex_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_MutexClass OSAPI Mutex
35  \ingroup OSAPIModule
36 
37  \brief Mutex API
38  */
39 
40 /*e \ingroup OSAPI_MutexClass
41  *
42  * Abstract Mutex object
43  */
44 struct OSAPI_Mutex;
45 
46 /*e \ingroup OSAPI_MutexClass
47  * Abstract Mutex type
48  */
49 typedef struct OSAPI_Mutex OSAPI_Mutex_T;
50 
51 #ifndef RTI_CERT
52 /*e \ingroup OSAPI_MutexClass
53  *
54  * \brief Delete a mutex.
55  *
56  * \param [in] mutex Delete a mutex created with \ref OSAPI_Mutex_new.
57  *
58  * \return RTI_TRUE on success, RTI_FALSE on failure
59  */
60 SHOULD_CHECK_RETURN OSAPIDllExport RTI_BOOL
61 OSAPI_Mutex_delete(OSAPI_Mutex_T *mutex);
62 #endif /* !RTI_CERT */
63 
64 /*e \ingroup OSAPI_MutexClass
65  *
66  * \brief Create a mutex.
67  *
68  * \return Pointer to a mutex in a not taken condition. NULL on failure.
69  *
70  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Mutex_delete
71  */
72 OSAPIDllExport OSAPI_Mutex_T*
73 OSAPI_Mutex_new(void);
74 
75 /*e \ingroup OSAPI_MutexClass
76  *
77  * \brief Take a mutex.
78  *
79  * \details
80  *
81  * A mutex can only be taken if it is not currently already taken
82  * by another thread; it CAN be taken if is it already taken by
83  * the same thread. In order to release a mutex, it must be
84  * given as many times a it has been taken. Note that `take` will
85  * block indefinitely.
86  * Note: the mutex is not required to support priority inversion;
87  * there is no protection against deadlocks or starvation.
88  *
89  * \param [in] mutex Take a mutex previously created with \ref OSAPI_Mutex_new.
90  *
91  * \return RTI_TRUE on success, RTI_FALSE on failure
92  *
93  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Mutex_give, \ref OSAPI_Mutex_new
94  *
95  */
96 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
97 OSAPI_Mutex_take(OSAPI_Mutex_T *mutex);
98 
99 /*e \ingroup OSAPI_MutexClass
100  *
101  * \brief Give a mutex.
102  *
103  * \details
104  *
105  * A mutex can only be given if it is owned by the calling thread. Furthermore,
106  * it must be given as many times as it has been taken.
107  *
108  * \param [in] mutex Take a mutex previously created with \ref OSAPI_Mutex_new.
109  *
110  * \return RTI_TRUE on success, RTI_FALSE on failure
111  *
112  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Mutex_take, \ref OSAPI_Mutex_new
113  *
114  */
115 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
116 OSAPI_Mutex_give(OSAPI_Mutex_T *mutex);
117 
118 #ifdef __cplusplus
119 } /* extern "C" */
120 #endif
121 
122 
123 #endif /* osapi_mutex_h */
RTI Connext Micro Version 2.4.4.0 Copyright © Thu Apr 30 2015 Real-Time Innovations, Inc