Embedded Multicore Building Blocks V1.0.0
mutex.h
1 /*
2  * Copyright (c) 2014-2017, Siemens AG. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  * 1. Redistributions of source code must retain the above copyright notice,
8  * this list of conditions and the following disclaimer.
9  *
10  * 2. Redistributions in binary form must reproduce the above copyright notice,
11  * this list of conditions and the following disclaimer in the documentation
12  * and/or other materials provided with the distribution.
13  *
14  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
15  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
18  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
19  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
20  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
21  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
22  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
23  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
24  * POSSIBILITY OF SUCH DAMAGE.
25  */
26 
27 #ifndef EMBB_BASE_C_MUTEX_H_
28 #define EMBB_BASE_C_MUTEX_H_
29 
30 #include <embb/base/c/internal/platform.h>
31 #include <embb/base/c/errors.h>
32 #include <embb/base/c/atomic.h>
33 
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
50 
51 #ifdef DOXYGEN
52 
55 typedef opaque_type embb_mutex_t;
56 
60 typedef opaque_type embb_spinlock_t;
61 #else
62 
65 typedef struct {
66 #ifdef EMBB_THREADING_ANALYSIS_MODE
67  /* Use a simple mutex in analysis mode to reflect the semantics of a lock and
68  to avoid potential problems with dynamic race detectors or concurrency testing
69  tools. */
70  embb_mutex_t mutex_;
71 #else
72  embb_atomic_int atomic_spin_variable_;
73 #endif /* EMBB_THREADING_ANALYSIS_MODE */
75 #endif /* DOXYGEN */
76 
80 enum {
85 };
86 
97 int embb_mutex_init(
98  embb_mutex_t* mutex,
100  int type
103  );
104 
117 int embb_mutex_lock(
118  embb_mutex_t* mutex
120  );
121 
135  embb_mutex_t* mutex
137  );
138 
153  embb_mutex_t* mutex
155  );
156 
165 void embb_mutex_destroy(
166  embb_mutex_t* mutex
168  );
169 
181 int embb_spin_init(
182  embb_spinlock_t* spinlock
184  );
185 
199 int embb_spin_lock(
200  embb_spinlock_t* spinlock
202  );
203 
217  embb_spinlock_t* spinlock,
219  unsigned int max_number_spins
223  );
224 
235 int embb_spin_unlock(
236  embb_spinlock_t* spinlock
238  );
239 
248 void embb_spin_destroy(
249  embb_spinlock_t* spinlock
251  );
252 
253 #ifdef __cplusplus
254 } /* Close extern "C" { */
255 #endif
256 
261 #endif /* EMBB_BASE_C_MUTEX_H_ */
void embb_spin_destroy(embb_spinlock_t *spinlock)
Destroys a spinlock and frees its resources.
Mutex can be locked only once by the same thread.
Definition: mutex.h:81
opaque_type embb_spinlock_t
Opaque type representing a spinlock.
Definition: mutex.h:60
Mutex can be locked recursively by the same thread.
Definition: mutex.h:83
int embb_spin_lock(embb_spinlock_t *spinlock)
Spins until the spinlock can be locked and locks it.
int embb_mutex_unlock(embb_mutex_t *mutex)
Unlocks a locked mutex.
int embb_mutex_init(embb_mutex_t *mutex, int type)
Initializes a mutex.
int embb_mutex_try_lock(embb_mutex_t *mutex)
Tries to lock the mutex and returns immediately.
int embb_spin_init(embb_spinlock_t *spinlock)
Initializes a spinlock.
int embb_spin_try_lock(embb_spinlock_t *spinlock, unsigned int max_number_spins)
Tries to lock the spinlock and returns if not successful.
int embb_mutex_lock(embb_mutex_t *mutex)
Waits until the mutex can be locked and locks it.
void embb_mutex_destroy(embb_mutex_t *mutex)
Destroys a mutex and frees its resources.
opaque_type embb_mutex_t
Opaque type representing a mutex.
Definition: mutex.h:55
int embb_spin_unlock(embb_spinlock_t *spinlock)
Unlocks a locked spinlock.