third_party/pigweed/repo/pw_sync/public/pw_sync/mutex.h

   1 // Copyright 2020 The Pigweed Authors
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
   4 // use this file except in compliance with the License. You may obtain a copy of
   5 // the License at
   6 //
   7 //     https://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  12 // License for the specific language governing permissions and limitations under
  13 // the License.
  14 #pragma once
  15
  16 #include <stdbool.h>
  17
  18 #include "pw_chrono/system_clock.h"
  19 #include "pw_preprocessor/util.h"
  20
  21 #ifdef __cplusplus
  22
  23 #include "pw_sync_backend/mutex_native.h"
  24
  25 namespace pw::sync {
  26
  27 // The Mutex is a synchronization primitive that can be used to protect
  28 // shared data from being simultaneously accessed by multiple threads.
  29 // It offers exclusive, non-recursive ownership semantics where priority
  30 // inheritance is used to solve the classic priority-inversion problem.
  31 // This is thread safe, but NOT IRQ safe.
  32 //
  33 // WARNING: In order to support global statically constructed Mutex, the backend
  34 // MUST ensure that any initialization required in your environment prior to the
  35 // creation and/or initialization of the native semaphore (e.g. kernel
  36 // initialization), is done before or during the invocation of the global static
  37 // C++ constructors.
  38 class Mutex {
  39  public:
  40   using native_handle_type = backend::NativeMutexHandle;
  41
  42   Mutex();
  43   ~Mutex();
  44   Mutex(const Mutex&) = delete;
  45   Mutex(Mutex&&) = delete;
  46   Mutex& operator=(const Mutex&) = delete;
  47   Mutex& operator=(Mutex&&) = delete;
  48
  49   // Locks the mutex, blocking indefinitely. Failures are fatal.
  50   //
  51   // PRECONDITION:
  52   //   The lock isn't already held by this thread. Recursive locking is
  53   //   undefined behavior.
  54   void lock();
  55
  56   // Attempts to lock the mutex in a non-blocking manner.
  57   // Returns true if the mutex was successfully acquired.
  58   //
  59   // PRECONDITION:
  60   //   The lock isn't already held by this thread. Recursive locking is
  61   //   undefined behavior.
  62   bool try_lock();
  63
  64   // Attempts to lock the mutex where, if needed, blocking for at least the
  65   // specified duration.
  66   // Returns true if the mutex was successfully acquired.
  67   //
  68   // PRECONDITION:
  69   //   The lock isn't already held by this thread. Recursive locking is
  70   //   undefined behavior.
  71   bool try_lock_for(chrono::SystemClock::duration for_at_least);
  72
  73   // Attempts to lock the mutex where, if needed, blocking until at least the
  74   // specified time_point.
  75   // Returns true if the mutex was successfully acquired.
  76   //
  77   // PRECONDITION:
  78   //   The lock isn't already held by this thread. Recursive locking is
  79   //   undefined behavior.
  80   bool try_lock_until(chrono::SystemClock::time_point until_at_least);
  81
  82   // Unlocks the mutex. Failures are fatal.
  83   //
  84   // PRECONDITION:
  85   //   The lock is held by this thread.
  86   void unlock();
  87
  88   native_handle_type native_handle();
  89
  90  private:
  91   // This may be a wrapper around a native type with additional members.
  92   backend::NativeMutex native_type_;
  93 };
  94
  95 }  // namespace pw::sync
  96
  97 #include "pw_sync_backend/mutex_inline.h"
  98
  99 using pw_sync_Mutex = pw::sync::Mutex;
 100
 101 #else  // !defined(__cplusplus)
 102
 103 typedef struct pw_sync_Mutex pw_sync_Mutex;
 104
 105 #endif  // __cplusplus
 106
 107 PW_EXTERN_C_START
 108
 109 void pw_sync_Mutex_Lock(pw_sync_Mutex* mutex);
 110 bool pw_sync_Mutex_TryLock(pw_sync_Mutex* mutex);
 111 bool pw_sync_Mutex_TryLockFor(pw_sync_Mutex* mutex,
 112                               pw_chrono_SystemClock_Duration for_at_least);
 113 bool pw_sync_Mutex_TryLockUntil(pw_sync_Mutex* mutex,
 114                                 pw_chrono_SystemClock_TimePoint until_at_least);
 115 void pw_sync_Mutex_Unlock(pw_sync_Mutex* mutex);
 116
 117 PW_EXTERN_C_END