allocator.h

// Copyright 2023 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 <cstddef>
#include <optional>
 
#include "pw_allocator/capability.h"
#include "pw_allocator/config.h"
#include "pw_allocator/deallocator.h"
#include "pw_allocator/fragmentation.h"
#include "pw_allocator/layout.h"
#include "pw_allocator/shared_ptr.h"
#include "pw_allocator/unique_ptr.h"
#include "pw_numeric/checked_arithmetic.h"
#include "pw_result/result.h"
 
namespace pw {
 
 
// Forward declare to break a circular dependency with shared_ptr.h.
template <typename T>
class SharedPtr;
 
class Allocator : public Deallocator {
 public:
  using Fragmentation = allocator::Fragmentation;
 
  [[nodiscard]] void* Allocate(Layout layout);
 
  template <typename T,
            int&... kExplicitGuard,
            std::enable_if_t<!std::is_array_v<T>, int> = 0,
            typename... Args>
  [[nodiscard]] T* New(Args&&... args) {
    void* ptr = Allocate(Layout::Of<T>());
    return ptr != nullptr ? new (ptr) T(std::forward<Args>(args)...) : nullptr;
  }
 
  template <typename T,
            int&... kExplicitGuard,
            typename ElementType = std::remove_extent_t<T>,
            std::enable_if_t<is_bounded_array_v<T>, int> = 0>
  [[nodiscard]] ElementType* New() {
    return NewArrayImpl<ElementType>(std::extent_v<T>, alignof(ElementType));
  }
 
  template <typename T,
            int&... kExplicitGuard,
            typename ElementType = std::remove_extent_t<T>,
            std::enable_if_t<is_unbounded_array_v<T>, int> = 0>
  [[nodiscard]] ElementType* New(size_t count) {
    return NewArrayImpl<ElementType>(count, alignof(ElementType));
  }
 
  //
  template <typename T,
            int&... kExplicitGuard,
            typename ElementType = std::remove_extent_t<T>,
            std::enable_if_t<is_unbounded_array_v<T>, int> = 0>
  [[nodiscard]] ElementType* New(size_t count, size_t alignment) {
    return NewArrayImpl<ElementType>(count, alignment);
  }
 
  template <typename T,
            int&... kExplicitGuard,
            std::enable_if_t<!std::is_array_v<T>, int> = 0,
            typename... Args>
  [[nodiscard]] UniquePtr<T> MakeUnique(Args&&... args) {
    return UniquePtr<T>(New<T>(std::forward<Args>(args)...), *this);
  }
 
  template <typename T, std::enable_if_t<is_unbounded_array_v<T>, int> = 0>
  [[nodiscard]] UniquePtr<T> MakeUnique(size_t size) {
    return MakeUnique<T>(size, alignof(std::remove_extent_t<T>));
  }
 
  template <typename T, std::enable_if_t<is_unbounded_array_v<T>, int> = 0>
  [[nodiscard]] UniquePtr<T> MakeUnique(size_t size, size_t alignment) {
    return UniquePtr<T>(New<T>(size, alignment), size, *this);
  }
 
  template <typename T, std::enable_if_t<is_bounded_array_v<T>, int> = 0>
  [[nodiscard]] UniquePtr<T> MakeUnique() {
    return UniquePtr<T>(New<T>(), std::extent_v<T>, this);
  }
 
// TODO(b/402489948): Remove when portable atomics are provided by `pw_atomic`.
#if PW_ALLOCATOR_HAS_ATOMICS
 
  template <typename T,
            int&... kExplicitGuard,
            std::enable_if_t<!std::is_array_v<T>, int> = 0,
            typename... Args>
  [[nodiscard]] SharedPtr<T> MakeShared(Args&&... args) {
    return SharedPtr<T>::template Create<Args...>(this,
                                                  std::forward<Args>(args)...);
  }
 
  template <typename T, std::enable_if_t<is_unbounded_array_v<T>, int> = 0>
  [[nodiscard]] SharedPtr<T> MakeShared(size_t size) {
    return MakeShared<T>(size, alignof(std::remove_extent_t<T>));
  }
 
  template <typename T, std::enable_if_t<is_unbounded_array_v<T>, int> = 0>
  [[nodiscard]] SharedPtr<T> MakeShared(size_t size, size_t alignment) {
    return SharedPtr<T>::Create(this, size, alignment);
  }
 
  template <typename T, std::enable_if_t<is_bounded_array_v<T>, int> = 0>
  [[nodiscard]] SharedPtr<T> MakeShared() {
    return SharedPtr<T>::Create(
        this, std::extent_v<T>, alignof(std::remove_extent_t<T>));
  }
 
// TODO(b/402489948): Remove when portable atomics are provided by `pw_atomic`.
#endif  // PW_ALLOCATOR_HAS_ATOMICS
 
  [[nodiscard]] bool Resize(void* ptr, size_t new_size);
 
  [[nodiscard]] void* Reallocate(void* ptr, Layout new_layout);
 
  size_t GetAllocated() const { return DoGetAllocated(); }
 
  std::optional<Fragmentation> MeasureFragmentation() const {
    return DoMeasureFragmentation();
  }
 
 protected:
  constexpr Allocator() = default;
 
  explicit constexpr Allocator(const Capabilities& capabilities)
      : Deallocator(Capability::kCanAllocateArbitraryLayout | capabilities) {}
 
  virtual void* DoAllocate(Layout layout) = 0;
 
  virtual bool DoResize([[maybe_unused]] void* ptr,
                        [[maybe_unused]] size_t new_size) {
    return false;
  }
 
  virtual void* DoReallocate(void* ptr, Layout new_layout);
 
  virtual size_t DoGetAllocated() const { return size_t(-1); }
 
  virtual std::optional<Fragmentation> DoMeasureFragmentation() const {
    return std::nullopt;
  }
 
 private:
  // Helper method for allocating arrays of objects.
  template <typename ElementType>
  ElementType* NewArrayImpl(size_t count, size_t alignment) {
    void* ptr = Allocate(Layout::Of<ElementType[]>(count).Align(alignment));
    return ptr != nullptr ? new (ptr) ElementType[count] : nullptr;
  }
};
 
namespace allocator {
 
// TODO(b/376730645): This deprecated alias cannot be removed yet due to a
// downstream dependency.
using Allocator [[deprecated("Use pw::Allocator instead")]] = ::pw::Allocator;
 
}  // namespace allocator
 
 
}  // namespace pw