µOS++ IIIe Reference 7.0.0
The third edition of µOS++, a POSIX inspired open source framework, written in C++
Loading...
Searching...
No Matches
os-mutex.h
Go to the documentation of this file.
1/*
2 * This file is part of the µOS++ distribution.
3 * (https://github.com/micro-os-plus)
4 * Copyright (c) 2016-2023 Liviu Ionescu. All rights reserved.
5 *
6 * Permission to use, copy, modify, and/or distribute this software
7 * for any purpose is hereby granted, under the terms of the MIT license.
8 *
9 * If a copy of the license was not distributed with this file, it can
10 * be obtained from https://opensource.org/licenses/mit/.
11 */
12
13#ifndef CMSIS_PLUS_RTOS_OS_MUTEX_H_
14#define CMSIS_PLUS_RTOS_OS_MUTEX_H_
15
16// ----------------------------------------------------------------------------
17
18#if defined(__cplusplus)
19
20// ----------------------------------------------------------------------------
21
23
24// ----------------------------------------------------------------------------
25
26#pragma GCC diagnostic push
27#if defined(__clang__)
28#pragma clang diagnostic ignored "-Wc++98-compat"
29#pragma clang diagnostic ignored "-Wdocumentation-unknown-command"
30#endif
31
32// ----------------------------------------------------------------------------
33
34namespace os
35{
36 namespace rtos
37 {
38 // ========================================================================
39
40#pragma GCC diagnostic push
41#if defined(__clang__)
42#pragma clang diagnostic ignored "-Wpadded"
43#elif defined(__GNUC__)
44#pragma GCC diagnostic ignored "-Wpadded"
45#endif
46
53 {
54 public:
55
60 using protocol_t = uint8_t;
61
67 struct protocol
68 {
72 enum
74 {
78 none = 0,
79
84
89
94
99 };
100 };
101
106 using robustness_t = uint8_t;
107
114 {
118 enum
120 {
125
130
135
139 max_ = robust
140 };
141 };
142
147 using type_t = uint8_t;
148
154 struct type
155 {
159 enum
160 : type_t
161 {
174
179
184 };
185 };
186
191 using count_t = uint16_t;
192
197 static constexpr count_t max_count = 0xFFFF;
198
199 // ======================================================================
200
207 {
208 public:
209
220 constexpr
221 attributes ();
222
223 protected:
224
229 constexpr
231
236 public:
237
238 // The rule of five.
239 attributes (const attributes&) = default;
240 attributes (attributes&&) = default;
242 operator= (const attributes&) = default;
244 operator= (attributes&&) = default;
245
249 ~attributes () = default;
250
255 public:
256
262 // Public members; no accessors and mutators required.
263 // Warning: must match the type & order of the C file header.
268
273
278
283
288
289 // Add more attributes here.
290
295 }; /* class attributes */
296
302
303 // ======================================================================
304
311 {
312 public:
313
324 constexpr
326
327 // The rule of five.
334
339
344 }; /* class attributes_recursive */
345
351
361 mutex (const attributes& attr = initializer_normal);
362
368 mutex (const char* name, const attributes& attr = initializer_normal);
369
374 // The rule of five.
375 mutex (const mutex&) = delete;
376 mutex (mutex&&) = delete;
377 mutex&
378 operator= (const mutex&) = delete;
379 mutex&
380 operator= (mutex&&) = delete;
381
389 ~mutex ();
390
405 bool
406 operator== (const mutex& rhs) const;
407
412 public:
413
441 lock (void);
442
467 try_lock (void);
468
492
506 unlock (void);
507
515 prio_ceiling (void) const;
516
541 thread::priority_t* old_prio_ceiling = nullptr);
542
553 consistent (void);
554
561 thread*
562 owner (void);
563
568 type_t
569 type (void);
570
576 protocol (void);
577
583 robustness (void);
584
592 reset (void);
593
598 protected:
599
600 friend class thread;
601
616 void
617 internal_init_ (void);
618
625 internal_try_lock_ (thread* th);
626
633 internal_unlock_ (thread* th);
634
635 void
636 internal_mark_owner_dead_ (void);
637
646 protected:
647
657 // Can be updated in different thread contexts.
658 thread* volatile owner_ = nullptr;
659
660#if !defined(OS_USE_RTOS_PORT_MUTEX)
662 clock* clock_ = nullptr;
663#endif
664
665 public:
666
667 // Intrusive node used to link this mutex to the owning thread.
668 // This is used for priority inheritance and robustness.
669 utils::double_list_links owner_links_;
670
671 protected:
672
673#if defined(OS_USE_RTOS_PORT_MUTEX)
674 friend class port::mutex;
675 os_mutex_port_data_t port_;
676#endif
677
678 // Can be updated in different thread contexts.
679 volatile count_t count_ = 0;
680
681 // Can be updated in different thread contexts.
682 volatile thread::priority_t initial_prio_ceiling_ =
684 volatile thread::priority_t prio_ceiling_ = thread::priority::highest;
685 volatile thread::priority_t boosted_prio_ = thread::priority::none;
686
687 bool owner_dead_ = false;
688 bool consistent_ = true;
689 bool recoverable_ = true;
690
691 // Constants set during construction.
692 const type_t type_; // normal, errorcheck, recursive
693 const protocol_t protocol_; // none, inherit, protect
694 const robustness_t robustness_; // stalled, robust
695 const count_t max_count_;
696
697 // Add more internal data.
698
707 };
708
714 class mutex_recursive : public mutex
715 {
716 public:
717
727
731 mutex_recursive (const char* name, const attributes& attr =
733
738 // The rule of five.
739 mutex_recursive (const mutex_recursive&) = delete;
740 mutex_recursive (mutex_recursive&&) = delete;
742 operator= (const mutex_recursive&) = delete;
744 operator= (mutex_recursive&&) = delete;
745
754
769 bool
770 operator== (const mutex_recursive& rhs) const;
771
776 };
777
778#pragma GCC diagnostic pop
779
780 // ==========================================================================
781
782 } /* namespace rtos */
783} /* namespace os */
784
785// ===== Inline & template implementations ====================================
786
787namespace os
788{
789 namespace rtos
790 {
791
792 // ========================================================================
793
794 constexpr
796 {
797 }
798
803 constexpr
805 mx_type (type)
806 {
807 }
808
813 // ========================================================================
814 constexpr
817 { type::recursive } // Use the protected constructor.
818 {
819 }
820
821 // ========================================================================
822
827 inline bool
828 mutex::operator== (const mutex& rhs) const
829 {
830 return this == &rhs;
831 }
832
836 inline thread*
838 {
839 return owner_;
840 }
841
845 inline mutex::type_t
847 {
848 return type_;
849 }
850
854 inline mutex::protocol_t
856 {
857 return protocol_;
858 }
859
865 {
866 return robustness_;
867 }
868
869 // ========================================================================
870
871 inline
873 mutex
874 { attr }
875 {
876 }
877
878 inline
879 mutex_recursive::mutex_recursive (const char* name, const attributes& attr) :
880 mutex
881 { name, attr }
882 {
883 }
884
885 inline
887 {
888 }
889
894 inline bool
896 {
897 return this == &rhs;
898 }
899
900 } /* namespace rtos */
901} /* namespace os */
902
903#pragma GCC diagnostic pop
904
905// ----------------------------------------------------------------------------
906
907#endif /* __cplusplus */
908
909// ----------------------------------------------------------------------------
910
911#endif /* CMSIS_PLUS_RTOS_OS_MUTEX_H_ */
Generic clock.
Definition os-clocks.h:59
Base class for attributes.
Definition os-decls.h:563
Base class for named system objects.
Definition os-decls.h:445
const char * name(void) const
Get object name.
Definition os-decls.h:759
Priority ordered list of threads.
Definition os-lists.h:550
Recursive mutex attributes.
Definition os-mutex.h:311
attributes_recursive & operator=(const attributes_recursive &)=default
attributes_recursive(const attributes_recursive &)=default
attributes_recursive(attributes_recursive &&)=default
~attributes_recursive()=default
Destruct the recursive mutex attributes object instance.
constexpr attributes_recursive()
Construct a recursive mutex attributes object instance.
Definition os-mutex.h:815
Mutex attributes.
Definition os-mutex.h:207
count_t mx_max_count
Attribute with the mutex maximum recursive count.
Definition os-mutex.h:287
constexpr attributes()
Construct a mutex attributes object instance.
Definition os-mutex.h:795
type_t mx_type
Attribute with the mutex type.
Definition os-mutex.h:282
robustness_t mx_robustness
Attribute with the mutex robustness.
Definition os-mutex.h:277
~attributes()=default
Destruct the mutex attributes object instance.
thread::priority_t mx_priority_ceiling
Attribute with the mutex priority ceiling.
Definition os-mutex.h:267
attributes & operator=(const attributes &)=default
protocol_t mx_protocol
Attribute with the mutex protocol.
Definition os-mutex.h:272
attributes(attributes &&)=default
attributes(const attributes &)=default
POSIX compliant recursive mutex.
Definition os-mutex.h:715
mutex_recursive(const attributes &attr=initializer_recursive)
Construct a recursive mutex object instance.
Definition os-mutex.h:872
bool operator==(const mutex_recursive &rhs) const
Compare mutexes.
Definition os-mutex.h:895
~mutex_recursive()
Destruct the recursive mutex object instance.
Definition os-mutex.h:886
POSIX compliant mutex.
Definition os-mutex.h:53
result_t reset(void)
Reset the mutex.
result_t lock(void)
Lock/acquire the mutex.
Definition os-mutex.cpp:955
thread::priority_t prio_ceiling(void) const
Get the priority ceiling of a mutex.
result_t timed_lock(clock::duration_t timeout)
Timed attempt to lock/acquire the mutex.
result_t try_lock(void)
Try to lock/acquire the mutex.
bool operator==(const mutex &rhs) const
Compare mutexes.
Definition os-mutex.h:828
~mutex()
Destruct the mutex object instance.
Definition os-mutex.cpp:526
result_t consistent(void)
Mark mutex as consistent.
thread * owner(void)
Get the thread that owns the mutex.
Definition os-mutex.h:837
result_t unlock(void)
Unlock/release the mutex.
POSIX compliant thread, using the default RTOS allocator.
Definition os-thread.h:250
port::clock::duration_t duration_t
Type of variables holding clock durations.
Definition os-clocks.h:76
uint8_t type_t
Type of variables holding mutex behaviours.
Definition os-mutex.h:147
uint16_t count_t
Type of variables holding mutex recursion counters.
Definition os-mutex.h:191
static const attributes_recursive initializer_recursive
Default recursive mutex initialiser.
Definition os-mutex.h:350
uint8_t protocol_t
Type of variables holding mutex protocols.
Definition os-mutex.h:60
uint8_t robustness_t
Type of variables holding mutex robustness.
Definition os-mutex.h:106
static constexpr count_t max_count
Constant with the maximum value for the recursion counter.
Definition os-mutex.h:197
static const attributes initializer_normal
Default normal mutex initialiser.
Definition os-mutex.h:301
uint8_t priority_t
Type of variables holding thread priorities.
Definition os-thread.h:271
uint32_t result_t
Type of values returned by RTOS functions.
Definition os-decls.h:96
System namespace.
Mutex protocols.
Definition os-mutex.h:68
@ max_
Maximum value, for validation purposes.
Definition os-mutex.h:98
@ default_
Default value. Differs from POSIX, which uses none.
Definition os-mutex.h:93
@ none
Priority and scheduling not affected by mutex ownership.
Definition os-mutex.h:78
@ inherit
Inherit priority from highest priority thread.
Definition os-mutex.h:83
@ protect
Execute at the highest priority.
Definition os-mutex.h:88
Mutex robustness.
Definition os-mutex.h:114
@ max_
Maximum value, for validation purposes.
Definition os-mutex.h:139
@ stalled
Normal robustness.
Definition os-mutex.h:124
@ default_
Default value.
Definition os-mutex.h:134
@ robust
Enhanced robustness at thread termination.
Definition os-mutex.h:129
@ max_
Maximum value, for validation purposes.
Definition os-mutex.h:183
@ normal
Normal mutex behaviour.
Definition os-mutex.h:165
@ default_
Default value.
Definition os-mutex.h:178
@ errorcheck
Check mutex behaviour.
Definition os-mutex.h:169
@ recursive
Recursive mutex behaviour.
Definition os-mutex.h:173