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