allocator.h

// Copyright 2024 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_containers/intrusive_forward_list.h"
#include "pw_multibuf/multibuf.h"
#include "pw_result/result.h"
#include "pw_sync/mutex.h"
 
namespace pw::multibuf {
 
enum class ContiguityRequirement {
  kAllowDiscontiguous,
  kNeedsContiguous,
};
 
inline constexpr ContiguityRequirement kAllowDiscontiguous =
    ContiguityRequirement::kAllowDiscontiguous;
inline constexpr ContiguityRequirement kNeedsContiguous =
    ContiguityRequirement::kNeedsContiguous;
 
class MultiBufAllocator {
 public:
  MultiBufAllocator() = default;
 
  MultiBufAllocator(MultiBufAllocator&) = delete;
  MultiBufAllocator& operator=(MultiBufAllocator&) = delete;
  MultiBufAllocator(MultiBufAllocator&&) = delete;
  MultiBufAllocator& operator=(MultiBufAllocator&&) = delete;
 
  virtual ~MultiBufAllocator() {}
 
  std::optional<MultiBuf> Allocate(size_t size);
 
  std::optional<MultiBuf> Allocate(size_t min_size, size_t desired_size);
 
  std::optional<MultiBuf> AllocateContiguous(size_t size);
 
  std::optional<MultiBuf> AllocateContiguous(size_t min_size,
                                             size_t desired_size);
 
  std::optional<size_t> GetBackingCapacity() { return DoGetBackingCapacity(); }
 
 protected:
  void MoreMemoryAvailable(size_t size_available,
                           size_t contiguous_size_available);
 
 private:
  friend class MultiBufAllocationFuture;
 
  // Instances of this class are informed when more memory becomes available.
  class MemoryAvailableDelegate
      : public IntrusiveForwardList<MemoryAvailableDelegate>::Item {
   public:
    explicit MemoryAvailableDelegate() = default;
    MemoryAvailableDelegate(MemoryAvailableDelegate&) = delete;
    MemoryAvailableDelegate& operator=(MemoryAvailableDelegate&) = delete;
    MemoryAvailableDelegate(MemoryAvailableDelegate&&) = delete;
    MemoryAvailableDelegate& operator=(MemoryAvailableDelegate&&) = delete;
    virtual ~MemoryAvailableDelegate() = default;
 
    // Callback from allocator when new memory being available. Function should
    // return true if object's need has been met which also indicates the object
    // can be released by the allocator.
    virtual bool HandleMemoryAvailable(MultiBufAllocator& alloc,
                                       size_t size_available,
                                       size_t contiguous_size_available) const
        PW_EXCLUSIVE_LOCKS_REQUIRED(lock_) = 0;
  };
 
  void AddMemoryAvailableDelegate(MemoryAvailableDelegate& delegate)
      PW_EXCLUSIVE_LOCKS_REQUIRED(lock_) {
    mem_delegates_.push_front(delegate);
  }
 
  void RemoveMemoryAvailableDelegate(MemoryAvailableDelegate& delegate)
      PW_EXCLUSIVE_LOCKS_REQUIRED(lock_) {
    mem_delegates_.remove(delegate);
  }
 
  virtual pw::Result<MultiBuf> DoAllocate(
      size_t min_size,
      size_t desired_size,
      ContiguityRequirement contiguity_requirement) = 0;
 
  virtual std::optional<size_t> DoGetBackingCapacity() = 0;
 
  sync::Mutex lock_;
  IntrusiveForwardList<MemoryAvailableDelegate> mem_delegates_
      PW_GUARDED_BY(lock_);
};
 
}  // namespace pw::multibuf