Raspberry Pi

Menu Toggle
Raspberry Pi By Raspberry Pi Ltd
mutex.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef _PICO_MUTEX_H
8 #define _PICO_MUTEX_H
9 
10 #include "pico/lock_core.h"
11 
12 #ifdef __cplusplus
13 extern "C" {
14 #endif
15 
47 typedef struct __packed_aligned {
48  lock_core_t core;
49  lock_owner_id_t owner;
50  uint8_t enter_count;
51 #if PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY
52  bool recursive;
53 #endif
54 } recursive_mutex_t;
55 
59 #if !PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY
60 typedef struct __packed_aligned mutex {
61  lock_core_t core;
62  lock_owner_id_t owner;
63 } mutex_t;
64 #else
65 typedef recursive_mutex_t mutex_t; // they are one and the same when backwards compatible with SDK1.2.0
66 #endif
67 
73 void mutex_init(mutex_t *mtx);
74 
82 void recursive_mutex_init(recursive_mutex_t *mtx);
83 
92 void mutex_enter_blocking(mutex_t *mtx);
93 
102 void recursive_mutex_enter_blocking(recursive_mutex_t *mtx);
103 
115 bool mutex_try_enter(mutex_t *mtx, uint32_t *owner_out);
116 
129 bool mutex_try_enter_block_until(mutex_t *mtx, absolute_time_t until);
130 
143 bool recursive_mutex_try_enter(recursive_mutex_t *mtx, uint32_t *owner_out);
144 
156 bool mutex_enter_timeout_ms(mutex_t *mtx, uint32_t timeout_ms);
157 
170 bool recursive_mutex_enter_timeout_ms(recursive_mutex_t *mtx, uint32_t timeout_ms);
171 
184 bool mutex_enter_timeout_us(mutex_t *mtx, uint32_t timeout_us);
185 
198 bool recursive_mutex_enter_timeout_us(recursive_mutex_t *mtx, uint32_t timeout_us);
199 
212 bool mutex_enter_block_until(mutex_t *mtx, absolute_time_t until);
213 
226 bool recursive_mutex_enter_block_until(recursive_mutex_t *mtx, absolute_time_t until);
227 
233 void mutex_exit(mutex_t *mtx);
234 
240 void recursive_mutex_exit(recursive_mutex_t *mtx);
241 
248 static inline bool mutex_is_initialized(mutex_t *mtx) {
249  return mtx->core.spin_lock != 0;
250 }
251 
258 static inline bool recursive_mutex_is_initialized(recursive_mutex_t *mtx) {
259  return mtx->core.spin_lock != 0;
260 }
261 
283 #define auto_init_mutex(name) static __attribute__((section(".mutex_array"))) mutex_t name
284 
306 #define auto_init_recursive_mutex(name) static __attribute__((section(".mutex_array"))) recursive_mutex_t name = { .core = { .spin_lock = (spin_lock_t *)1 /* marker for runtime_init */ }, .owner = 0, .enter_count = 0 }
307 
308 #ifdef __cplusplus
309 }
310 #endif
311 #endif
mutex_try_enter_block_until
bool mutex_try_enter_block_until(mutex_t *mtx, absolute_time_t until)
Attempt to take ownership of a mutex until the specified timeIf the mutex wasn't owned, this method will immediately claim the mutex for the caller and return true. If the mutex is owned by the caller, this method will immediately return false, If the mutex is owned by someone else, this method will try to claim it until the specified time, returning true if it succeeds, or false on timeout.
Definition: mutex.c:83
mutex_enter_block_until
bool mutex_enter_block_until(mutex_t *mtx, absolute_time_t until)
Wait for mutex until a specific timeWait until the specific time to take ownership of the mutex...
Definition: mutex.c:127
recursive_mutex_try_enter
bool recursive_mutex_try_enter(recursive_mutex_t *mtx, uint32_t *owner_out)
Attempt to take ownership of a recursive mutexIf the mutex wasn't owned or was owned by the caller...
Definition: mutex.c:94
recursive_mutex_enter_blocking
void recursive_mutex_enter_blocking(recursive_mutex_t *mtx)
Take ownership of a recursive mutexThis function will block until the caller can be granted ownership...
Definition: mutex.c:48
recursive_mutex_t
struct __packed_aligned recursive_mutex_t
recursive mutex instance
recursive_mutex_enter_timeout_us
bool recursive_mutex_enter_timeout_us(recursive_mutex_t *mtx, uint32_t timeout_us)
Wait for recursive mutex with timeoutWait for up to the specific time to take ownership of the recurs...
Definition: mutex.c:123
absolute_time_t
Definition: types.h:33
mutex_exit
void mutex_exit(mutex_t *mtx)
Release ownership of a mutex.
Definition: mutex.c:172
recursive_mutex_is_initialized
static bool recursive_mutex_is_initialized(recursive_mutex_t *mtx)
Test for recursive mutex initialized state.
Definition: mutex.h:258
lock_owner_id_t
#define lock_owner_id_t
type to use to store the 'owner' of a lock.By default this is int8_t as it only needs to store the co...
Definition: lock_core.h:80
mutex_enter_timeout_us
bool mutex_enter_timeout_us(mutex_t *mtx, uint32_t timeout_us)
Wait for mutex with timeoutWait for up to the specific time to take ownership of the mutex...
Definition: mutex.c:119
mutex_enter_blocking
void mutex_enter_blocking(mutex_t *mtx)
Take ownership of a mutexThis function will block until the caller can be granted ownership of the mu...
Definition: mutex.c:29
recursive_mutex_init
void recursive_mutex_init(recursive_mutex_t *mtx)
Initialise a recursive mutex structureA recursive mutex may be entered in a nested fashion by the sam...
Definition: mutex.c:19
mutex_try_enter
bool mutex_try_enter(mutex_t *mtx, uint32_t *owner_out)
Attempt to take ownership of a mutexIf the mutex wasn't owned, this will claim the mutex for the call...
Definition: mutex.c:64
__packed_aligned
recursive mutex instance
Definition: mutex.h:47
mutex_init
void mutex_init(mutex_t *mtx)
Initialise a mutex structure.
Definition: mutex.c:10
mutex_t
struct __packed_aligned mutex mutex_t
regular (non recursive) mutex instance
mutex_is_initialized
static bool mutex_is_initialized(mutex_t *mtx)
Test for mutex initialized state.
Definition: mutex.h:248
recursive_mutex_enter_block_until
bool recursive_mutex_enter_block_until(recursive_mutex_t *mtx, absolute_time_t until)
Wait for mutex until a specific timeWait until the specific time to take ownership of the mutex...
Definition: mutex.c:151
lock_core.h
lock_core
Definition: lock_core.h:53
recursive_mutex_exit
void recursive_mutex_exit(recursive_mutex_t *mtx)
Release ownership of a recursive mutex.
Definition: mutex.c:185
recursive_mutex_enter_timeout_ms
bool recursive_mutex_enter_timeout_ms(recursive_mutex_t *mtx, uint32_t timeout_ms)
Wait for recursive mutex with timeoutWait for up to the specific time to take ownership of the recurs...
Definition: mutex.c:115
__packed_aligned::enter_count
uint8_t enter_count
owner id LOCK_INVALID_OWNER_ID for unowned
Definition: mutex.h:50
mutex
regular (non recursive) mutex instance
Definition: mutex.h:60
mutex_enter_timeout_ms
bool mutex_enter_timeout_ms(mutex_t *mtx, uint32_t timeout_ms)
Wait for mutex with timeoutWait for up to the specific time to take ownership of the mutex...
Definition: mutex.c:111