RTI Connext DDS Micro  Version 2.4.6
 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  *
87  * Note: the mutex is not required to support priority inversion;
88  * there is no protection against deadlocks or starvation.
89  *
90  * \param [in] mutex Take a mutex previously created with \ref OSAPI_Mutex_new.
91  *
92  * \return RTI_TRUE on success, RTI_FALSE on failure
93  *
94  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Mutex_give, \ref OSAPI_Mutex_new
95  *
96  */
97 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
98 OSAPI_Mutex_take(OSAPI_Mutex_T *mutex);
99 
100 /*e \ingroup OSAPI_MutexClass
101  *
102  * \brief Give a mutex.
103  *
104  * \details
105  *
106  * A mutex can only be given if it is owned by the calling thread. Furthermore,
107  * it must be given as many times as it has been taken.
108  *
109  * \param [in] mutex Take a mutex previously created with \ref OSAPI_Mutex_new.
110  *
111  * \return RTI_TRUE on success, RTI_FALSE on failure
112  *
113  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Mutex_take, \ref OSAPI_Mutex_new
114  *
115  */
116 MUST_CHECK_RETURN OSAPIDllExport RTI_BOOL
117 OSAPI_Mutex_give(OSAPI_Mutex_T *mutex);
118 
119 #ifdef __cplusplus
120 } /* extern "C" */
121 #endif
122 
123 
124 #endif /* osapi_mutex_h */
RTI Connext DDS Micro Version 2.4.6 Copyright © Mon Jan 25 2016 Real-Time Innovations, Inc