pthread_mutex_attr.h
8.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
/*
* Copyright (C) 2014 Freie Universität Berlin
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @ingroup pthread
* @{
* @file
* @brief Attributes for pthread mutexes.
* @note Do not include this header file directly, but pthread.h.
*/
#ifndef SYS__POSIX__PTHREAD_MUTEX_ATTR__H
#define SYS__POSIX__PTHREAD_MUTEX_ATTR__H
#include <errno.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @def PTHREAD_MUTEX_NORMAL
* @brief A non-error correcting mutex (default).
*/
/**
* @def PTHREAD_MUTEX_RECURSIVE
* @brief A mutex that allows recursive locking.
* @note Not implemented, yet.
*/
/**
* @def PTHREAD_MUTEX_ERRORCHECK
* @brief A mutex that fails with `EDEADLK` if recursive locking was detected.
* @note Not implemented, yet.
*/
/**
* @def PTHREAD_MUTEX_DEFAULT
* @brief The default mutex kind for RIOT.
* @note Not implemented, yet.
*/
#define PTHREAD_MUTEX_NORMAL 0
#define PTHREAD_MUTEX_RECURSIVE 1
#define PTHREAD_MUTEX_ERRORCHECK 2
#define PTHREAD_MUTEX_DEFAULT PTHREAD_MUTEX_NORMAL
/**
* @def PTHREAD_PRIO_NONE
* @brief No priority inheritance.
* @details Prone to inversed priorities.
* The default mutex protocol.
*/
/**
* @def PTHREAD_PRIO_INHERIT
* @brief If a thread attempts to acquire a held lock,
* the holding thread gets its dynamic priority increased up to
* the priority of the blocked thread
* @note Not implemented, yet.
*/
#define PTHREAD_PRIO_NONE 0
#define PTHREAD_PRIO_INHERIT 1
/**
* @def PTHREAD_PRIO_PROTECT
* @brief Not implemented, yet.
*/
/**
* @def PTHREAD_MUTEX_STALLED
* @brief Mutexes aren't automatically released on the end of a thread.
* @see #pthread_cleanup_push() for an option to unlock mutexes on the end of a thread.
* @note This is the default.
*/
/**
* @def PTHREAD_MUTEX_ROBUST
* @brief Mutexes that are held at the exit of a thread get released automatically.
* @note Not implemented, yet.
*/
#define PTHREAD_PRIO_PROTECT 2
#define PTHREAD_MUTEX_STALLED 0
#define PTHREAD_MUTEX_ROBUST 1
/**
* @brief This type is unused right now, and only exists for POSIX compatibility.
*/
typedef struct
{
int pshared; /**< Whether to share the mutex with child processes. */
int kind; /**< Type of the mutex. */
int protocol; /**< Priority inheritance of the mutex. */
int robustness; /**< What to do if a thread terminates while it holds a mutex. */
} pthread_mutexattr_t;
/**
* @brief Initialize a pthread_mutexattr_t
* @details A zeroed out datum is initialized
* @note This function is not implemented, yet.
* @param[out] attr Datum to initialize.
* @returns `0` on success.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_init(pthread_mutexattr_t *attr);
/**
* @brief Destroys a pthread_mutexattr_t
* @details There is no need to ever call this function.
* This function is a no-op.
* @note This function is not implemented, yet.
* @param[in,out] attr Datum to destroy.
* @returns `0` on success.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
/**
* @brief Queries the attribute set whether to share the mutex with child processes.
* @note Since RIOT does not implement processes, this value is unused.
* @param[in] attr Attribute set to query.
* @param[out] pshared Either #PTHREAD_PROCESS_SHARED or #PTHREAD_PROCESS_PRIVATE.
* @returns `0` on success.
* `EINVAL` if `attr` or `pshared` are `NULL`.
*/
int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared);
/**
* @brief Set whether to share the mutex with child processes.
* @note Since RIOT does not implement processes, this value is unused.
* @param[in,out] attr Attribute set to change.
* @param[in] pshared Either #PTHREAD_PROCESS_SHARED or #PTHREAD_PROCESS_PRIVATE.
* @returns `0` on success.
* `EINVAL` if `pshared` is neither #PTHREAD_PROCESS_SHARED nor #PTHREAD_PROCESS_PRIVATE.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared);
/**
* @brief Query the type of the mutex to create.
* @note This implementation only supports PTHREAD_MUTEX_NORMAL mutexes.
* @param[in] attr Attribute set to query.
* @param[out] kind Either #PTHREAD_MUTEX_NORMAL or #PTHREAD_MUTEX_RECURSIVE or #PTHREAD_MUTEX_ERRORCHECK.
* @returns `0` on success.
* `EINVAL` if `attr` or `kind` are `NULL`.
*/
int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *kind);
/**
* @brief Sets the type of the mutex to create.
* @note This implementation only supports `PTHREAD_MUTEX_NORMAL` mutexes.
* @param[in,out] attr Attribute set to change.
* @param[in] kind Either #PTHREAD_MUTEX_NORMAL or #PTHREAD_MUTEX_RECURSIVE or #PTHREAD_MUTEX_ERRORCHECK.
* @returns `0` on success.
* `EINVAL` if the value of `kind` is unsupported.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int kind);
/**
* @brief Query the priority inheritance of the mutex to create.
* @note This implementation only supports `PTHREAD_PRIO_NONE` mutexes.
* @param[in] attr Attribute set to query
* @param[out] protocol Either #PTHREAD_PRIO_NONE or #PTHREAD_PRIO_INHERIT or #PTHREAD_PRIO_PROTECT.
* @returns `0` on success.
* `EINVAL` if `attr` or `protocol` are `NULL`.
*/
int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, int *protocol);
/**
* @brief Sets the priority inheritance of the mutex to create.
* @note This implementation only supports `PTHREAD_PRIO_NONE` mutexes.
* @param[in,out] attr Attribute set to change.
* @param[in] protocol Either #PTHREAD_PRIO_NONE or #PTHREAD_PRIO_INHERIT or #PTHREAD_PRIO_PROTECT.
* @returns `0` on success.
* `EINVAL` if the value of `protocol` is unsupported.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol);
/* Return in *PRIOCEILING the mutex prioceiling attribute in *ATTR. */
int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr, int *prioceiling);
/* Set the mutex prioceiling attribute in *ATTR to PRIOCEILING. */
int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling);
/**
* @brief Query the attribute set whether to create a robut mutex.
* @details A "robust" mutex releases gets released automagically if the threads exits while it hold the mutex.
* If the thread is cancellable, only rubust mutex should be held.
* @note This implementation does not support robust mutexes, yet.
* As it doesn't implement cancellation points, yet, this should not pose a problem.
* @param[in] attr Attribute set to query.
* @param[out] robustness Either #PTHREAD_MUTEX_STALLED or #PTHREAD_MUTEX_ROBUST.
* @returns `0` on success.
* `EINVAL` if the value of `protocol` is unsupported.
* `EINVAL` if `attr` or `robustness` is `NULL`.
*/
int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr, int *robustness);
/**
* @brief Set whether the mutex to create should be robust.
* @details A "robust" mutex releases gets released automagically if the threads exits while it hold the mutex.
* If the thread is cancellable, only rubust mutex should be held.
* @note This implementation does not support robust mutexes, yet.
* As it doesn't implement cancellation points, yet, this should not pose a problem.
* @param[in,out] attr Attribute set to change.
* @param[in] robustness Either #PTHREAD_MUTEX_STALLED or #PTHREAD_MUTEX_ROBUST.
* @returns `0` on success.
* `EINVAL` if the value of `robustness` is unsupported.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr, int robustness);
#ifdef __cplusplus
}
#endif
#endif /* SYS__POSIX__PTHREAD_MUTEX_ATTR__H */
/**
* @}
*/