borrow.h

// Copyright 2021 The Pigweed Authors
//
// 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
//
//     https://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.
#pragma once
 
#include <optional>
#include <type_traits>
 
#include "pw_assert/assert.h"
#include "pw_sync/lock_annotations.h"
#include "pw_sync/lock_traits.h"
#include "pw_sync/virtual_basic_lockable.h"
 
namespace pw::sync {
 
 
template <typename GuardedType,
          typename LockType = pw::sync::VirtualBasicLockable>
class BorrowedPointer {
 public:
  ~BorrowedPointer() {
    if (lock_ != nullptr) {
      lock_->unlock();
    }
  }
 
  template <typename G, typename L>
  BorrowedPointer(BorrowedPointer<G, L>&& other)
      : lock_(other.lock_), object_(other.object_) {
    static_assert(
        std::is_assignable_v<GuardedType*&, G*>,
        "Attempted to construct a BorrowedPointer from another whose "
        "GuardedType* is not assignable to this object's GuardedType*.");
    static_assert(std::is_assignable_v<LockType*&, L*>,
                  "Attempted to construct a BorrowedPointer from another whose "
                  "LockType* is not assignable to this object's Lock*.");
    other.lock_ = nullptr;
    other.object_ = nullptr;
  }
 
  template <typename G, typename L>
  BorrowedPointer& operator=(BorrowedPointer<G, L>&& other) {
    static_assert(
        std::is_assignable_v<GuardedType*&, G*>,
        "Attempted to construct a BorrowedPointer from another whose "
        "GuardedType* is not assignable to this object's GuardedType*.");
    static_assert(std::is_assignable_v<LockType*&, L*>,
                  "Attempted to construct a BorrowedPointer from another whose "
                  "LockType* is not assignable to this object's Lock*.");
    lock_ = other.lock_;
    object_ = other.object_;
    other.lock_ = nullptr;
    other.object_ = nullptr;
    return *this;
  }
  BorrowedPointer(const BorrowedPointer&) = delete;
  BorrowedPointer& operator=(const BorrowedPointer&) = delete;
 
  GuardedType* operator->() {
    PW_ASSERT(object_ != nullptr);  // Ensure this isn't a stale moved instance.
    return object_;
  }
 
  const GuardedType* operator->() const {
    PW_ASSERT(object_ != nullptr);  // Ensure this isn't a stale moved instance.
    return object_;
  }
 
  GuardedType& operator*() {
    PW_ASSERT(object_ != nullptr);  // Ensure this isn't a stale moved instance.
    return *object_;
  }
 
  const GuardedType& operator*() const {
    PW_ASSERT(object_ != nullptr);  // Ensure this isn't a stale moved instance.
    return *object_;
  }
 
 private:
  template <typename, typename>
  friend class Borrowable;
 
  constexpr BorrowedPointer(LockType& lock, GuardedType& object)
      : lock_(&lock), object_(&object) {}
 
  LockType* lock_;
  GuardedType* object_;
 
  template <typename, typename>
  friend class BorrowedPointer;
};
 
// clang-format off
// clang-format on
template <typename GuardedType,
          typename LockType = pw::sync::VirtualBasicLockable>
class Borrowable {
 public:
  static_assert(is_basic_lockable_v<LockType>,
                "lock type must satisfy BasicLockable");
 
  constexpr Borrowable(GuardedType& object, LockType& lock) noexcept
      : lock_(&lock), object_(&object) {}
 
  template <typename U>
  constexpr Borrowable(const Borrowable<U, LockType>& other)
      : lock_(other.lock_), object_(other.object_) {}
 
  Borrowable(const Borrowable&) = default;
  Borrowable& operator=(const Borrowable&) = default;
  Borrowable(Borrowable&& other) = default;
  Borrowable& operator=(Borrowable&& other) = default;
 
  BorrowedPointer<GuardedType, LockType> acquire() const
      PW_NO_LOCK_SAFETY_ANALYSIS {
    lock_->lock();
    return Borrow();
  }
 
  template <int&... ExplicitArgumentBarrier,
            typename T = LockType,
            typename = std::enable_if_t<is_lockable_v<T>>>
  std::optional<BorrowedPointer<GuardedType, LockType>> try_acquire() const
      PW_NO_LOCK_SAFETY_ANALYSIS {
    if (!lock_->try_lock()) {
      return std::nullopt;
    }
    return Borrow();
  }
 
 private:
  // Befriend all template instantiations of this class and the Timed subtype.
  template <typename, typename>
  friend class Borrowable;
 
  template <typename, typename>
  friend class TimedBorrowable;
 
  BorrowedPointer<GuardedType, LockType> Borrow() const {
    return BorrowedPointer<GuardedType, LockType>(*lock_, *object_);
  }
 
  LockType* lock_;
  GuardedType* object_;
};
 
 
}  // namespace pw::sync