synchronized_value.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright 2026 ETC Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *******************************************************************************
 * This file is a part of EtcPal. For more information, go to:
 * https://github.com/ETCLabs/EtcPal
 ******************************************************************************/
 
 
 
#ifndef ETCPAL_CPP_SYNCHRONIZED_VALUE_H_
#define ETCPAL_CPP_SYNCHRONIZED_VALUE_H_
 
#include <memory>
#include <stdexcept>
#include <type_traits>
#include <utility>
 
#include "etcpal/cpp/common.h"
#include "etcpal/cpp/mutex.h"
#include "etcpal/cpp/recursive_mutex.h"
 
namespace etcpal
{
 
template <typename T, typename LockType = Mutex>
class SynchronizedValue;
template <typename T, typename LockType = Mutex>
class ConstUniqueLockPtr;
template <typename T, typename LockType = Mutex>
class UniqueLockPtr;
 
namespace detail
{
template <typename...>
struct FirstType
{
  using type = void;  // NOLINT(readability-identifier-naming)
};
template <typename First, typename... Rest>
struct FirstType<First, Rest...>
{
  using type = First;  // NOLINT(readability-identifier-naming)
};
}  // namespace detail
 
struct AdoptLockTag
{
};
struct DeferLockTag
{
};
struct TryToLockTag
{
};
 
template <typename LockType>
struct SupportsTimedLock : std::false_type
{
};
template <>
struct SupportsTimedLock<Mutex> : std::integral_constant<bool, ETCPAL_MUTEX_HAS_TIMED_LOCK>
{
};
template <>
struct SupportsTimedLock<RecursiveMutex> : std::integral_constant<bool, ETCPAL_RECURSIVE_MUTEX_HAS_TIMED_LOCK>
{
};
 
template <typename T, typename LockType = Mutex>
class ConstStrictLockPtr
{
public:
  explicit ConstStrictLockPtr(const SynchronizedValue<T, LockType>& sync) : sync_(&sync)
  {
    if (!sync_->lock_.Lock())
      ETCPAL_THROW(std::runtime_error("etcpal SynchronizedValue lock failed."));
  }
 
  ConstStrictLockPtr(const SynchronizedValue<T, LockType>& sync, AdoptLockTag /*unused*/) noexcept : sync_(&sync) {}
 
  explicit ConstStrictLockPtr(ConstUniqueLockPtr<T, LockType>&& other) : sync_(other.sync_)
  {
    if (!other.owns_)
      ETCPAL_THROW(std::runtime_error("etcpal ConstStrictLockPtr constructed from a non-owning handle."));
    other.sync_ = nullptr;
    other.owns_ = false;
  }
 
  ConstStrictLockPtr(const ConstStrictLockPtr&) = delete;
  ConstStrictLockPtr& operator=(const ConstStrictLockPtr&) = delete;
  ConstStrictLockPtr& operator=(ConstStrictLockPtr&&) = delete;
 
  ConstStrictLockPtr(ConstStrictLockPtr&& other) noexcept : sync_(other.sync_) { other.sync_ = nullptr; }
 
  ~ConstStrictLockPtr() noexcept
  {
    if (sync_)
      sync_->lock_.Unlock();
  }
 
  const T& operator*() const noexcept { return sync_->value_; }
  const T* operator->() const noexcept { return std::addressof(sync_->value_); }
 
protected:
  // NOLINTNEXTLINE(cppcoreguidelines-non-private-member-variables-in-classes) - derived handles need direct access
  const SynchronizedValue<T, LockType>* sync_;
};
 
template <typename T, typename LockType = Mutex>
class StrictLockPtr : public ConstStrictLockPtr<T, LockType>
{
public:
  explicit StrictLockPtr(SynchronizedValue<T, LockType>& sync) : ConstStrictLockPtr<T, LockType>(sync) {}
 
  StrictLockPtr(SynchronizedValue<T, LockType>& sync, AdoptLockTag /*unused*/) noexcept
      : ConstStrictLockPtr<T, LockType>(sync, AdoptLockTag{})
  {
  }
 
  explicit StrictLockPtr(UniqueLockPtr<T, LockType>&& other) : ConstStrictLockPtr<T, LockType>(std::move(other)) {}
 
  using ConstStrictLockPtr<T, LockType>::operator*;
  using ConstStrictLockPtr<T, LockType>::operator->;
 
  // The casts below are sound: mutable handles can only be constructed from a non-const SynchronizedValue.
  T& operator*() noexcept
  {
    return const_cast<T&>(this->sync_->value_);  // NOLINT(cppcoreguidelines-pro-type-const-cast)
  }
  T* operator->() noexcept
  {
    return const_cast<T*>(std::addressof(this->sync_->value_));  // NOLINT(cppcoreguidelines-pro-type-const-cast)
  }
};
 
template <typename T, typename LockType>
class ConstUniqueLockPtr
{
public:
  explicit ConstUniqueLockPtr(const SynchronizedValue<T, LockType>& sync) : sync_(&sync), owns_(false) { Lock(); }
 
  ConstUniqueLockPtr(const SynchronizedValue<T, LockType>& sync, AdoptLockTag /*unused*/) noexcept
      : sync_(&sync), owns_(true)
  {
  }
 
  ConstUniqueLockPtr(const SynchronizedValue<T, LockType>& sync, DeferLockTag /*unused*/) noexcept
      : sync_(&sync), owns_(false)
  {
  }
 
  ConstUniqueLockPtr(const SynchronizedValue<T, LockType>& sync, TryToLockTag /*unused*/, int timeout_ms = 0) noexcept
      : sync_(&sync), owns_(sync.TryLockFor(timeout_ms))
  {
  }
 
  ConstUniqueLockPtr(const ConstUniqueLockPtr&) = delete;
  ConstUniqueLockPtr& operator=(const ConstUniqueLockPtr&) = delete;
  ConstUniqueLockPtr& operator=(ConstUniqueLockPtr&&) = delete;
 
  ConstUniqueLockPtr(ConstUniqueLockPtr&& other) noexcept : sync_(other.sync_), owns_(other.owns_)
  {
    other.sync_ = nullptr;
    other.owns_ = false;
  }
 
  ~ConstUniqueLockPtr() noexcept { Unlock(); }
 
  explicit operator bool() const noexcept { return owns_; }
  bool OwnsLock() const noexcept { return owns_; }
 
  void Unlock() noexcept
  {
    if (owns_)
    {
      sync_->lock_.Unlock();
      owns_ = false;
    }
  }
 
  void Lock()
  {
    if (!sync_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle does not reference a lock."));
    if (owns_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle already owns the lock."));
    if (!sync_->lock_.Lock())
      ETCPAL_THROW(std::runtime_error("etcpal SynchronizedValue lock failed."));
    owns_ = true;
  }
 
  bool TryLock(int timeout_ms = 0)
  {
    if (!sync_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle does not reference a lock."));
    if (owns_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle already owns the lock."));
    owns_ = sync_->TryLockFor(timeout_ms);
    return owns_;
  }
 
  void Release() noexcept
  {
    sync_ = nullptr;
    owns_ = false;
  }
 
  const T& operator*() const
  {
    if (!owns_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle does not own the lock."));
    return sync_->value_;
  }
  const T* operator->() const
  {
    if (!owns_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle does not own the lock."));
    return std::addressof(sync_->value_);
  }
 
protected:
  // NOLINT below: the derived mutable handle and the strict-pointer conversion need direct access.
  const SynchronizedValue<T, LockType>* sync_;  // NOLINT(cppcoreguidelines-non-private-member-variables-in-classes)
  bool                                  owns_;  // NOLINT(cppcoreguidelines-non-private-member-variables-in-classes)
 
  friend class ConstStrictLockPtr<T, LockType>;
};
 
template <typename T, typename LockType>
class UniqueLockPtr : public ConstUniqueLockPtr<T, LockType>
{
public:
  explicit UniqueLockPtr(SynchronizedValue<T, LockType>& sync) : ConstUniqueLockPtr<T, LockType>(sync) {}
 
  UniqueLockPtr(SynchronizedValue<T, LockType>& sync, AdoptLockTag /*unused*/) noexcept
      : ConstUniqueLockPtr<T, LockType>(sync, AdoptLockTag{})
  {
  }
 
  UniqueLockPtr(SynchronizedValue<T, LockType>& sync, DeferLockTag /*unused*/) noexcept
      : ConstUniqueLockPtr<T, LockType>(sync, DeferLockTag{})
  {
  }
 
  UniqueLockPtr(SynchronizedValue<T, LockType>& sync, TryToLockTag /*unused*/, int timeout_ms = 0) noexcept
      : ConstUniqueLockPtr<T, LockType>(sync, TryToLockTag{}, timeout_ms)
  {
  }
 
  using ConstUniqueLockPtr<T, LockType>::operator*;
  using ConstUniqueLockPtr<T, LockType>::operator->;
 
  // The casts below are sound: mutable handles can only be constructed from a non-const SynchronizedValue.
  T& operator*()
  {
    if (!this->owns_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle does not own the lock."));
    return const_cast<T&>(this->sync_->value_);  // NOLINT(cppcoreguidelines-pro-type-const-cast)
  }
  T* operator->()
  {
    if (!this->owns_)
      ETCPAL_THROW(std::runtime_error("etcpal lock handle does not own the lock."));
    return const_cast<T*>(std::addressof(this->sync_->value_));  // NOLINT(cppcoreguidelines-pro-type-const-cast)
  }
};
 
template <typename T, typename LockType>
class SynchronizedValue
{
public:
  template <typename... Args,
            typename = typename std::enable_if<
                std::is_constructible<T, Args&&...>::value &&
                !std::is_same<typename std::decay<typename detail::FirstType<Args...>::type>::type,
                              SynchronizedValue>::value>::type>
  // The noexcept clause assumes LockType's default constructor cannot throw, which holds for the EtcPal
  // lock types but is not checked (they do not declare it noexcept, so a trait check would always be false).
  explicit SynchronizedValue(Args&&... args) noexcept(std::is_nothrow_constructible<T, Args...>::value)
      : value_(std::forward<Args>(args)...)
  {
  }
 
  T&        GetValueUnsafe() noexcept { return value_; }
  LockType& GetLockUnsafe() noexcept { return lock_; }
 
 
  StrictLockPtr<T, LockType> operator->() { return StrictLockPtr<T, LockType>(*this); }
  ConstStrictLockPtr<T, LockType> operator->() const { return ConstStrictLockPtr<T, LockType>(*this); }
 
  StrictLockPtr<T, LockType> Synchronize() { return StrictLockPtr<T, LockType>(*this); }
  ConstStrictLockPtr<T, LockType> Synchronize() const { return ConstStrictLockPtr<T, LockType>(*this); }
 
  UniqueLockPtr<T, LockType> TryToSynchronize(int timeout_ms = 0) noexcept
  {
    return UniqueLockPtr<T, LockType>(*this, TryToLockTag{}, timeout_ms);
  }
  ConstUniqueLockPtr<T, LockType> TryToSynchronize(int timeout_ms = 0) const noexcept
  {
    return ConstUniqueLockPtr<T, LockType>(*this, TryToLockTag{}, timeout_ms);
  }
 
 
  UniqueLockPtr<T, LockType>      UniqueSynchronize() { return UniqueLockPtr<T, LockType>(*this); }
  ConstUniqueLockPtr<T, LockType> UniqueSynchronize() const { return ConstUniqueLockPtr<T, LockType>(*this); }
 
  UniqueLockPtr<T, LockType> DeferSynchronize() noexcept { return UniqueLockPtr<T, LockType>(*this, DeferLockTag{}); }
  ConstUniqueLockPtr<T, LockType> DeferSynchronize() const noexcept
  {
    return ConstUniqueLockPtr<T, LockType>(*this, DeferLockTag{});
  }
 
  UniqueLockPtr<T, LockType> AdoptSynchronize() noexcept { return UniqueLockPtr<T, LockType>(*this, AdoptLockTag{}); }
  ConstUniqueLockPtr<T, LockType> AdoptSynchronize() const noexcept
  {
    return ConstUniqueLockPtr<T, LockType>(*this, AdoptLockTag{});
  }
 
  template <typename F>
  decltype(auto) Apply(F&& func)
  {
    static_assert(!std::is_reference<decltype(std::forward<F>(func)(std::declval<T&>()))>::value,
                  "Apply must not return a reference; it would outlive the lock");
    auto lock = Synchronize();
    return std::forward<F>(func)(*lock);
  }
  template <typename F>
  decltype(auto) Apply(F&& func) const
  {
    static_assert(!std::is_reference<decltype(std::forward<F>(func)(std::declval<const T&>()))>::value,
                  "Apply must not return a reference; it would outlive the lock");
    auto lock = Synchronize();
    return std::forward<F>(func)(*lock);
  }
 
private:
  friend class ConstStrictLockPtr<T, LockType>;
  friend class StrictLockPtr<T, LockType>;
  friend class ConstUniqueLockPtr<T, LockType>;
  friend class UniqueLockPtr<T, LockType>;
 
  // Honor the timeout only where the platform supports timed locking; otherwise poll, so an unsupported
  // platform never silently blocks forever (etcpal_*_timed_lock() with a nonzero timeout is Lock() there).
  bool TryLockFor(int timeout_ms) const noexcept
  {
    return SupportsTimedLock<LockType>::value ? lock_.TryLock(timeout_ms) : lock_.TryLock(0);
  }
 
  T                value_;
  mutable LockType lock_;
};
 
}  // namespace etcpal
 
#endif  // ETCPAL_CPP_SYNCHRONIZED_VALUE_H_