v2.0.0
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
13extern "C" {
14#endif
15
47 typedef struct {
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 mutex {
61 lock_core_t core;
62 lock_owner_id_t owner;
63} mutex_t;
64#else
65typedef recursive_mutex_t mutex_t; // they are one and the same when backwards compatible with SDK1.2.0
66#endif
67
73void mutex_init(mutex_t *mtx);
74
82void 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
308void runtime_init_mutex(void);
309
310#ifdef __cplusplus
311}
312#endif
313#endif
lock_owner_id_t
#define lock_owner_id_t
type to use to store the 'owner' of a lock.
Definition: lock_core.h:81
recursive_mutex_exit
void recursive_mutex_exit(recursive_mutex_t *mtx)
Release ownership of a recursive mutex.
recursive_mutex_init
void recursive_mutex_init(recursive_mutex_t *mtx)
Initialise a recursive mutex structure.
Definition: mutex.c:52
mutex_enter_timeout_ms
bool mutex_enter_timeout_ms(mutex_t *mtx, uint32_t timeout_ms)
Wait for mutex with timeout.
mutex_enter_timeout_us
bool mutex_enter_timeout_us(mutex_t *mtx, uint32_t timeout_us)
Wait for mutex with timeout.
mutex_enter_blocking
void mutex_enter_blocking(mutex_t *mtx)
Take ownership of a mutex.
mutex_enter_block_until
bool mutex_enter_block_until(mutex_t *mtx, absolute_time_t until)
Wait for mutex until a specific time.
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 time.
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 time.
recursive_mutex_is_initialized
static bool recursive_mutex_is_initialized(recursive_mutex_t *mtx)
Test for recursive mutex initialized state.
Definition: mutex.h:258
mutex_try_enter
bool mutex_try_enter(mutex_t *mtx, uint32_t *owner_out)
Attempt to take ownership of a mutex.
mutex_init
void mutex_init(mutex_t *mtx)
Initialise a mutex structure.
Definition: mutex.c:43
mutex_t
struct mutex mutex_t
regular (non recursive) mutex instance
recursive_mutex_enter_blocking
void recursive_mutex_enter_blocking(recursive_mutex_t *mtx)
Take ownership of a recursive mutex.
recursive_mutex_enter_timeout_ms
bool recursive_mutex_enter_timeout_ms(recursive_mutex_t *mtx, uint32_t timeout_ms)
Wait for recursive mutex with timeout.
recursive_mutex_try_enter
bool recursive_mutex_try_enter(recursive_mutex_t *mtx, uint32_t *owner_out)
Attempt to take ownership of a recursive mutex.
mutex_is_initialized
static bool mutex_is_initialized(mutex_t *mtx)
Test for mutex initialized state.
Definition: mutex.h:248
recursive_mutex_enter_timeout_us
bool recursive_mutex_enter_timeout_us(recursive_mutex_t *mtx, uint32_t timeout_us)
Wait for recursive mutex with timeout.
mutex_exit
void mutex_exit(mutex_t *mtx)
Release ownership of a mutex.
absolute_time_t
uint64_t absolute_time_t
An opaque 64 bit timestamp in microseconds.
Definition: types.h:43
lock_core.h
lock_core
Definition: lock_core.h:53
mutex
regular (non recursive) mutex instance
Definition: mutex.h:60
recursive_mutex_t
recursive mutex instance
Definition: mutex.h:47
recursive_mutex_t::enter_count
uint8_t enter_count
owner id LOCK_INVALID_OWNER_ID for unowned
Definition: mutex.h:50