Repository: raspberrypi/pico-sdk
File: src/common/pico_sync/include/pico/mutex.h (C/C++)

Code before:
#endif

/** \file mutex.h
 *  \defgroup mutex mutex
 *  \ingroup pico_sync
 * \brief Mutex API for non IRQ mutual exclusion between cores
 *
 * Mutexes are application level locks usually used protecting data structures that might be used by
 * multiple threads of executions. Unlike critical sections, the mutex protected code is not necessarily
 * required/expected to complete quickly, as no other sytem wide locks are held on account of an acquired mutex.
 *
 * When acquired, the mutex has an owner (see \ref lock_get_caller_owner_id) which with the plain SDK is just
 * the acquiring core, but in an RTOS it could be a task, or an IRQ handler context.
 *
 * Two variants of mutex are provided; \ref mutex_t (and associated mutex_ functions) is a regular mutex that cannot
 * be acquired recursively by the same owner (a deadlock will occur if you try). \ref recursive_mutex
 * (and associated recursive_mutex_ functions) is a recursive mutex that can be recursively obtained by
 * the same caller, at the expense of some more overhead when acquiring and releasing.
 *
 * It is generally a bad idea to call blocking mutex_ or recursive_mutex_ functions from within an IRQ handler
 . It is valid to call \ref mutex_try_enter or \ref recursive_mutex_try_enter from within an IRQ handler, if the operation
 * that would be conducted under lock can be skipped if the mutex is locked (at least by the same core).
 *
 * NOTE: For backwards compatibility with version 1.2.0 of the SDK, if the define
 * PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY is set to 1, then the the regular mutex_ functions
 * may also be used for recursive mutexes. This flag will be removed in a future version of the SDK.
 *
 * See \ref critical_section.h for protecting access between multiple cores AND IRQ handlers
 */

/*! \brief recursive mutex instance
 * \ingroup mutex
 */
typedef struct __packed_aligned  {
    lock_core_t core;
    lock_owner_id_t owner;      //! owner id LOCK_INVALID_OWNER_ID for unowned
    uint8_t enter_count;        //! ownership count
#if PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY
    bool recursive;
#endif
} recursive_mutex_t;

/*! \brief regular (non recursive) mutex instance
 * \ingroup mutex
 */
#if !PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY
typedef struct __packed_aligned mutex {
    lock_core_t core;
    lock_owner_id_t owner;      //! owner id LOCK_INVALID_OWNER_ID for unowned
} mutex_t;
#else

Review comment (suggestion):
I dunno if it's worth wrapping the newly-added `recursive_mutex_xxxx` functions in a `#if !PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY` for clarity? Or would that be more of a hindrance than a help? :man_shrugging: 

Code after:
#endif

/** \file mutex.h
 *  \defgroup mutex mutex
 *  \ingroup pico_sync
 * \brief Mutex API for non IRQ mutual exclusion between cores
 *
 * Mutexes are application level locks usually used protecting data structures that might be used by
 * multiple threads of execution. Unlike critical sections, the mutex protected code is not necessarily
 * required/expected to complete quickly, as no other sytem wide locks are held on account of an acquired mutex.
 *
 * When acquired, the mutex has an owner (see \ref lock_get_caller_owner_id) which with the plain SDK is just
 * the acquiring core, but in an RTOS it could be a task, or an IRQ handler context.
 *
 * Two variants of mutex are provided; \ref mutex_t (and associated mutex_ functions) is a regular mutex that cannot
 * be acquired recursively by the same owner (a deadlock will occur if you try). \ref recursive_mutex_t
 * (and associated recursive_mutex_ functions) is a recursive mutex that can be recursively obtained by
 * the same caller, at the expense of some more overhead when acquiring and releasing.
 *
 * It is generally a bad idea to call blocking mutex_ or recursive_mutex_ functions from within an IRQ handler.
 * It is valid to call \ref mutex_try_enter or \ref recursive_mutex_try_enter from within an IRQ handler, if the operation
 * that would be conducted under lock can be skipped if the mutex is locked (at least by the same owner).
 *
 * NOTE: For backwards compatibility with version 1.2.0 of the SDK, if the define
 * PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY is set to 1, then the the regular mutex_ functions
 * may also be used for recursive mutexes. This flag will be removed in a future version of the SDK.
 *
 * See \ref critical_section.h for protecting access between multiple cores AND IRQ handlers
 */

/*! \brief recursive mutex instance
 * \ingroup mutex
 */
typedef struct __packed_aligned  {
    lock_core_t core;
    lock_owner_id_t owner;      //! owner id LOCK_INVALID_OWNER_ID for unowned
    uint8_t enter_count;        //! ownership count
#if PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY
    bool recursive;
#endif
} recursive_mutex_t;

/*! \brief regular (non recursive) mutex instance
 * \ingroup mutex
 */
#if !PICO_MUTEX_ENABLE_SDK120_COMPATIBILITY
typedef struct __packed_aligned mutex {
    lock_core_t core;
    lock_owner_id_t owner;      //! owner id LOCK_INVALID_OWNER_ID for unowned
} mutex_t;
#else