chunk.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 <optional>
#include <utility>
 
#include "pw_assert/assert.h"
#include "pw_bytes/span.h"
#include "pw_sync/mutex.h"
 
namespace pw::multibuf {
 
class ChunkRegionTracker;
class OwnedChunk;
 
class Chunk {
 public:
  Chunk() = delete;
  // Not copyable or movable.
  Chunk(Chunk&) = delete;
  Chunk& operator=(Chunk&) = delete;
  Chunk(Chunk&&) = delete;
  Chunk& operator=(Chunk&&) = delete;
 
  std::byte* data() { return span_.data(); }
  const std::byte* data() const { return span_.data(); }
  size_t size() const { return span_.size(); }
  [[nodiscard]] bool empty() const { return span_.empty(); }
 
  std::byte& operator[](size_t index) { return span_[index]; }
  const std::byte& operator[](size_t index) const { return span_[index]; }
 
  // Container declarations
  using element_type = std::byte;
  using value_type = std::byte;
  using size_type = size_t;
  using difference_type = ptrdiff_t;
  using pointer = std::byte*;
  using const_pointer = const std::byte*;
  using reference = std::byte&;
  using const_reference = const std::byte&;
  using iterator = std::byte*;
  using const_iterator = const std::byte*;
  using reverse_iterator = std::byte*;
  using const_reverse_iterator = const std::byte*;
 
  std::byte* begin() { return span_.data(); }
  const std::byte* begin() const { return cbegin(); }
  const std::byte* cbegin() const { return span_.data(); }
  std::byte* end() { return span_.data() + span_.size(); }
  const std::byte* end() const { return cend(); }
  const std::byte* cend() const { return span_.data() + span_.size(); }
 
  [[nodiscard]] bool CanMerge(const Chunk& next_chunk) const;
 
  bool Merge(OwnedChunk& next_chunk);
 
  [[nodiscard]] bool ClaimPrefix(size_t bytes_to_claim);
 
  [[nodiscard]] bool ClaimSuffix(size_t bytes_to_claim);
 
  void DiscardPrefix(size_t bytes_to_discard);
 
  void Slice(size_t begin, size_t end);
 
  void Truncate(size_t len);
 
  std::optional<OwnedChunk> TakePrefix(size_t bytes_to_take);
 
  std::optional<OwnedChunk> TakeSuffix(size_t bytes_to_take);
 
 private:
  Chunk(ChunkRegionTracker* region_tracker, ByteSpan span)
      : region_tracker_(region_tracker),
        next_in_region_(nullptr),
        prev_in_region_(nullptr),
        next_in_buf_(nullptr),
        span_(span) {}
 
  // NOTE: these functions are logically
  // `PW_EXCLUSIVE_LOCKS_REQUIRED(region_tracker_->lock_)`, however this
  // annotation cannot be applied due to the forward declaration of
  // `region_tracker_`.
  void InsertAfterInRegionList(Chunk* new_chunk);
  void InsertBeforeInRegionList(Chunk* new_chunk);
  void RemoveFromRegionList();
 
  void Free();
 
  ChunkRegionTracker* const region_tracker_;
 
  Chunk* next_in_region_;
 
  Chunk* prev_in_region_;
 
  Chunk* next_in_buf_;
 
  ByteSpan span_;
 
  friend class ChunkRegionTracker;  // For the constructor
  friend class OwnedChunk;          // for `Free`.
  friend class MultiBuf;            // for `next_in_buf_`.
  friend class MultiBufChunks;      // for `Free` and `next_in_buf_`.
};
 
class ChunkRegionTracker {
 public:
  std::optional<OwnedChunk> CreateFirstChunk();
 
 protected:
  ChunkRegionTracker() = default;
  virtual ~ChunkRegionTracker() = default;
 
  virtual void Destroy() = 0;
 
  virtual ByteSpan Region() const = 0;
 
  virtual void* AllocateChunkClass() = 0;
 
  virtual void DeallocateChunkClass(void*) = 0;
 
 private:
  pw::sync::Mutex lock_;
  friend Chunk;
};
 
class OwnedChunk {
 public:
  OwnedChunk() : inner_(nullptr) {}
  OwnedChunk(OwnedChunk&& other) noexcept : inner_(other.inner_) {
    other.inner_ = nullptr;
  }
  OwnedChunk& operator=(OwnedChunk&& other) noexcept {
    inner_ = other.inner_;
    other.inner_ = nullptr;
    return *this;
  }
  ~OwnedChunk() { Release(); }
 
  std::byte* data() {
    return const_cast<std::byte*>(std::as_const(*this).data());
  }
  const std::byte* data() const {
    return inner_ == nullptr ? nullptr : inner_->data();
  }
 
  size_t size() const { return inner_ == nullptr ? 0 : inner_->size(); }
 
  std::byte& operator[](size_t index) { return data()[index]; }
  std::byte operator[](size_t index) const { return data()[index]; }
 
  // Container declarations
  using element_type = std::byte;
  using value_type = std::byte;
  using size_type = size_t;
  using difference_type = ptrdiff_t;
  using pointer = std::byte*;
  using const_pointer = const std::byte*;
  using reference = std::byte&;
  using const_reference = const std::byte&;
  using iterator = std::byte*;
  using const_iterator = const std::byte*;
  using reverse_iterator = std::byte*;
  using const_reverse_iterator = const std::byte*;
 
  std::byte* begin() { return data(); }
  const std::byte* begin() const { return cbegin(); }
  const std::byte* cbegin() const { return data(); }
  std::byte* end() { return data() + size(); }
  const std::byte* end() const { return cend(); }
  const std::byte* cend() const { return data() + size(); }
 
  Chunk& operator*() { return *inner_; }
  const Chunk& operator*() const { return *inner_; }
  Chunk* operator->() { return inner_; }
  const Chunk* operator->() const { return inner_; }
 
  void Release();
 
  Chunk* Take() && {
    Chunk* result = inner_;
    inner_ = nullptr;
    return result;
  }
 
 private:
  OwnedChunk(Chunk* inner) : inner_(inner) {}
 
  Chunk* inner_;
 
  friend class Chunk;
  friend class ChunkRegionTracker;
  friend class MultiBuf;
  friend class MultiBufChunks;
};
 
}  // namespace pw::multibuf