circularBuffer.hpp

Go to the documentation of this file.

/*
 *   Copyright 2025 Huawei Technologies Co., Ltd.
 *
 * 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
 *
 *     http://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 <hicr/core/exceptions.hpp>
 
namespace HiCR::channel
{
 
class CircularBuffer
{
  public:
 
  CircularBuffer(size_t capacity, __volatile__ size_t *headAdvanceCounter, __volatile__ size_t *tailAdvanceCounter)
    : _capacity(capacity),
      _headAdvanceCounter(headAdvanceCounter),
      _tailAdvanceCounter(tailAdvanceCounter)
 
  {}
 
  virtual ~CircularBuffer() = default;
 
  [[nodiscard]] __INLINE__ size_t getHeadPosition() const noexcept { return *_headAdvanceCounter % _capacity; }
 
  [[nodiscard]] __INLINE__ size_t getTailPosition() const noexcept { return *_tailAdvanceCounter % _capacity; }
 
  __INLINE__ void advanceHead(const size_t n = 1, bool useCachedDepth = false)
  {
    // Current depth
    const auto curDepth = useCachedDepth ? getCachedDepth() : getDepth();
 
    // Calculating new depth
    const auto newDepth = curDepth + n;
 
    // Sanity check
    if (newDepth > _capacity)
      HICR_THROW_FATAL("New buffer depth (_depth (%lu) + n (%lu) = %lu) exceeded capacity (%lu) on increase. This is probably a bug in HiCR.\n", curDepth, n, newDepth, _capacity);
 
    // Advance head
    *_headAdvanceCounter = *_headAdvanceCounter + n;
  }
 
  __INLINE__ void advanceTail(const size_t n = 1)
  {
    // Current depth
    const auto curDepth = getDepth();
 
    // Sanity check
    if (n > curDepth)
      HICR_THROW_FATAL("Circular buffer depth (%lu) smaller than number of elements (%lu) to decrease on advance tail. This is probably a bug in HiCR.\n", curDepth, n);
 
    // Advance tail
    *_tailAdvanceCounter = *_tailAdvanceCounter + n;
  }
 
  [[nodiscard]] __INLINE__ size_t getCapacity() const noexcept { return _capacity; }
 
  [[nodiscard]] __INLINE__ size_t getDepth() const noexcept { return calculateDepth(*_headAdvanceCounter, *_tailAdvanceCounter); }
 
  void setCachedDepth(size_t depth) { _cachedDepth = depth; }
 
  [[nodiscard]] __INLINE__ size_t getCachedDepth() const noexcept { return _cachedDepth; }
 
  [[nodiscard]] __INLINE__ bool isFull() const noexcept { return getDepth() == _capacity; }
 
  [[nodiscard]] __INLINE__ bool isEmpty() const noexcept { return *_headAdvanceCounter == *_tailAdvanceCounter; }
 
  __INLINE__ void setHead(const size_t headAdvanceCounter)
  {
    // Sanity check
    if (*_tailAdvanceCounter > headAdvanceCounter)
      HICR_THROW_FATAL("Circular buffer new head advance value is smaller than tail's (%lu < %lu). This is probably a bug in HiCR.\n", headAdvanceCounter, *_tailAdvanceCounter);
 
    // Calculating new depth
    const auto newDepth = calculateDepth(headAdvanceCounter, *_tailAdvanceCounter);
 
    // Sanity check
    if (newDepth > _capacity) HICR_THROW_FATAL("Circular new buffer depth (%lu) exceeded capacity (%lu) on setHead. This is probably a bug in HiCR.\n", newDepth, _capacity);
 
    // Setting head
    *_headAdvanceCounter = headAdvanceCounter;
  }
 
  __INLINE__ void setTail(const size_t tailAdvanceCounter)
  {
    // Sanity check
    if (tailAdvanceCounter > *_headAdvanceCounter)
      HICR_THROW_FATAL("Circular buffer new tail advance value exceeds head (%lu > %lu). This is probably a bug in HiCR.\n", tailAdvanceCounter, *_headAdvanceCounter);
 
    // Calculating new depth
    const auto newDepth = calculateDepth(*_headAdvanceCounter, tailAdvanceCounter);
 
    // Sanity check
    if (newDepth > _capacity) HICR_THROW_FATAL("Circular buffer new buffer depth (%lu) exceeded capacity (%lu) on setTail. This is probably a bug in HiCR.\n", newDepth, _capacity);
 
    // Setting head
    *_tailAdvanceCounter = tailAdvanceCounter;
  }
 
  [[nodiscard]] __INLINE__ size_t getHeadAdvanceCounter() const noexcept { return *_headAdvanceCounter; }
 
  [[nodiscard]] __INLINE__ size_t getTailAdvanceCounter() const noexcept { return *_tailAdvanceCounter; }
 
  private:
 
  const size_t _capacity;
 
  __volatile__ size_t *const _headAdvanceCounter;
 
  __volatile__ size_t *const _tailAdvanceCounter;
 
  size_t _cachedDepth{0};
 
  protected:
 
  __INLINE__ static size_t calculateDepth(const size_t headAdvanceCounter, const size_t tailAdvanceCounter)
  {
    if (headAdvanceCounter < tailAdvanceCounter)
    {
      HICR_THROW_FATAL("Head index (%lu) < tail index (%lu). This is a critical bug in HiCR!\n", headAdvanceCounter, tailAdvanceCounter);
    }
    return headAdvanceCounter - tailAdvanceCounter;
  }
};
 
} // namespace HiCR::channel