entry.h

// Copyright 2025 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 <cstdint>
#include <limits>
 
#include "pw_allocator/deallocator.h"
#include "pw_allocator/internal/control_block.h"
#include "pw_bytes/span.h"
#include "pw_containers/dynamic_deque.h"
#include "pw_preprocessor/compiler.h"
 
namespace pw::multibuf::v2::internal {
 
enum class Mutability {
  kMutable,
  kConst,
};
 
struct Entry {
  using Deque = DynamicDeque<Entry>;
  using size_type = Deque::size_type;
  using difference_type = Deque::difference_type;
 
  static constexpr size_t kMaxSize = ~(1U << 15);
 
  static constexpr size_type kMemoryContextIndex = 0;
 
  static constexpr size_type kDataIndex = 1;
 
  static constexpr size_type kBaseViewIndex = 2;
 
  static constexpr size_type kMinEntriesPerChunk = 3;
 
  [[nodiscard]] static constexpr size_type num_chunks(
      const Deque& deque, size_type entries_per_chunk) {
    return deque.size() / entries_per_chunk;
  }
 
  [[nodiscard]] static constexpr size_type num_layers(
      size_type entries_per_chunk) {
    return entries_per_chunk - Entry::kMinEntriesPerChunk + 1;
  }
 
  [[nodiscard]] static constexpr size_type memory_context_index(
      size_type chunk, size_type entries_per_chunk) {
    return chunk * entries_per_chunk + kMemoryContextIndex;
  }
 
  [[nodiscard]] static constexpr size_type data_index(
      size_type chunk, size_type entries_per_chunk) {
    return chunk * entries_per_chunk + kDataIndex;
  }
 
  [[nodiscard]] static constexpr size_type base_view_index(
      size_type chunk, size_type entries_per_chunk) {
    return chunk * entries_per_chunk + kBaseViewIndex;
  }
 
  [[nodiscard]] static constexpr size_type view_index(
      size_type chunk, size_type entries_per_chunk, size_type layer) {
    return chunk * entries_per_chunk + kBaseViewIndex + layer - 1;
  }
 
  [[nodiscard]] static constexpr size_type top_view_index(
      size_type chunk, size_type entries_per_chunk) {
    return (chunk + 1) * entries_per_chunk - 1;
  }
 
  [[nodiscard]] static constexpr std::byte* GetData(
      const Deque& deque, size_type chunk, size_type entries_per_chunk) {
    return deque[data_index(chunk, entries_per_chunk)].data;
  }
 
  [[nodiscard]] static constexpr bool IsOwned(const Deque& deque,
                                              size_type chunk,
                                              size_type entries_per_chunk) {
    return deque[base_view_index(chunk, entries_per_chunk)].base_view.owned;
  }
 
  [[nodiscard]] static constexpr bool IsShared(const Deque& deque,
                                               size_type chunk,
                                               size_type entries_per_chunk) {
    return deque[base_view_index(chunk, entries_per_chunk)].base_view.shared;
  }
 
  [[nodiscard]] static constexpr bool IsSealed(const Deque& deque,
                                               size_type chunk,
                                               size_type entries_per_chunk) {
    return entries_per_chunk == Entry::kMinEntriesPerChunk
               ? false
               : deque[top_view_index(chunk, entries_per_chunk)].view.sealed;
  }
 
  [[nodiscard]] static constexpr Deallocator& GetDeallocator(
      const Deque& deque, size_type chunk, size_type entries_per_chunk) {
    PW_ASSERT(IsOwned(deque, chunk, entries_per_chunk));
    return *(deque[memory_context_index(chunk, entries_per_chunk)].deallocator);
  }
 
  [[nodiscard]] static constexpr allocator::internal::ControlBlock&
  GetControlBlock(const Deque& deque,
                  size_type chunk,
                  size_type entries_per_chunk) {
    PW_ASSERT(IsShared(deque, chunk, entries_per_chunk));
    return *(
        deque[memory_context_index(chunk, entries_per_chunk)].control_block);
  }
 
  [[nodiscard]] static constexpr bool IsBoundary(const Deque& deque,
                                                 size_type chunk,
                                                 size_type entries_per_chunk,
                                                 size_type layer) {
    return layer == 1 ? true
                      : deque[view_index(chunk, entries_per_chunk, layer)]
                            .view.boundary;
  }
 
  [[nodiscard]] static constexpr bool IsBoundary(const Deque& deque,
                                                 size_type chunk,
                                                 size_type entries_per_chunk) {
    return IsBoundary(
        deque, chunk, entries_per_chunk, num_layers(entries_per_chunk));
  }
 
  [[nodiscard]] static constexpr size_type GetOffset(
      const Deque& deque,
      size_type chunk,
      size_type entries_per_chunk,
      size_type layer) {
    return layer == 1
               ? deque[base_view_index(chunk, entries_per_chunk)]
                     .base_view.offset
               : deque[view_index(chunk, entries_per_chunk, layer)].view.offset;
  }
 
  [[nodiscard]] static constexpr size_type GetOffset(
      const Deque& deque, size_type chunk, size_type entries_per_chunk) {
    return GetOffset(
        deque, chunk, entries_per_chunk, num_layers(entries_per_chunk));
  }
 
  [[nodiscard]] static constexpr size_type GetRelativeOffset(
      const Deque& deque,
      size_type chunk,
      size_type entries_per_chunk,
      size_type layer) {
    return layer == 1 ? GetOffset(deque, chunk, entries_per_chunk, layer)
                      : (GetOffset(deque, chunk, entries_per_chunk, layer) -
                         GetOffset(deque, chunk, entries_per_chunk, layer - 1));
  }
 
  [[nodiscard]] static constexpr size_type GetRelativeOffset(
      const Deque& deque, size_type chunk, size_type entries_per_chunk) {
    return GetRelativeOffset(
        deque, chunk, entries_per_chunk, num_layers(entries_per_chunk));
  }
 
  [[nodiscard]] static constexpr size_type GetLength(
      const Deque& deque,
      size_type chunk,
      size_type entries_per_chunk,
      size_type layer) {
    return layer == 1
               ? deque[base_view_index(chunk, entries_per_chunk)]
                     .base_view.length
               : deque[view_index(chunk, entries_per_chunk, layer)].view.length;
  }
 
  [[nodiscard]] static constexpr size_type GetLength(
      const Deque& deque, size_type chunk, size_type entries_per_chunk) {
    return GetLength(
        deque, chunk, entries_per_chunk, num_layers(entries_per_chunk));
  }
 
  [[nodiscard]] static constexpr ByteSpan GetView(const Deque& deque,
                                                  size_type chunk,
                                                  size_type entries_per_chunk,
                                                  size_type layer) {
    std::byte* data = GetData(deque, chunk, entries_per_chunk);
    size_type offset = GetOffset(deque, chunk, entries_per_chunk, layer);
    size_type length = GetLength(deque, chunk, entries_per_chunk, layer);
    return ByteSpan(data + offset, length);
  }
 
  [[nodiscard]] static constexpr ByteSpan GetView(const Deque& deque,
                                                  size_type chunk,
                                                  size_type entries_per_chunk) {
    return GetView(
        deque, chunk, entries_per_chunk, num_layers(entries_per_chunk));
  }
 
  struct BaseView {
    size_type offset : 15;
 
    size_type owned : 1;
 
    size_type length : 15;
 
    size_type shared : 1;
  };
 
  struct View {
    size_type offset : 15;
 
    size_type sealed : 1;
 
    size_type length : 15;
 
    size_type boundary : 1;
  };
 
  union {
    Deallocator* deallocator;
 
    allocator::internal::ControlBlock* control_block;
 
    std::byte* data;
 
    BaseView base_view;
 
    View view;
  };
 
  // All fields should fit into a pointer's width.
  static_assert(sizeof(BaseView) <= sizeof(void*));
  static_assert(sizeof(View) <= sizeof(void*));
};
 
}  // namespace pw::multibuf::v2::internal