mbed-os/platform/include/platform/CircularBuffer.h

/* mbed Microcontroller Library
 * Copyright (c) 2015-2019 ARM Limited
 * SPDX-License-Identifier: Apache-2.0
 *
 * 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.
 */
#ifndef MBED_CIRCULARBUFFER_H
#define MBED_CIRCULARBUFFER_H

#include <stdint.h>
#include "platform/mbed_critical.h"
#include "platform/mbed_assert.h"
#include "platform/Span.h"
#include "platform/mbed_atomic.h"

namespace mbed {

namespace internal {
/* Detect if CounterType of the Circular buffer is of unsigned type. */
template<typename T>
struct is_unsigned {
    static const bool value = false;
};
template<>
struct is_unsigned<unsigned char> {
    static const bool value = true;
};
template<>
struct is_unsigned<unsigned short> {
    static const bool value = true;
};
template<>
struct is_unsigned<unsigned int> {
    static const bool value = true;
};
template<>
struct is_unsigned<unsigned long> {
    static const bool value = true;
};
template<>
struct is_unsigned<unsigned long long> {
    static const bool value = true;
};
}

/** \addtogroup platform-public-api */
/** @{*/
/**
 * \defgroup platform_CircularBuffer CircularBuffer functions
 * @{
 */

/** Templated Circular buffer class
 *
 *  @note Synchronization level: Interrupt safe.
 *  @note CounterType must be unsigned and consistent with BufferSize.
 */
template<typename T, uint32_t BufferSize, typename CounterType = uint32_t>
class CircularBuffer {
public:
    CircularBuffer() : _head(0), _tail(0), _full(false)
    {
        static_assert(
            internal::is_unsigned<CounterType>::value,
            "CounterType must be unsigned"
        );

        static_assert(
            (sizeof(CounterType) >= sizeof(uint32_t)) ||
            (BufferSize < (((uint64_t) 1) << (sizeof(CounterType) * 8))),
            "Invalid BufferSize for the CounterType"
        );
    }

    ~CircularBuffer()
    {
    }

    /** Push the transaction to the buffer. This overwrites the buffer if it's full.
     *
     * @param data Data to be pushed to the buffer.
     */
    void push(const T &data)
    {
        core_util_critical_section_enter();

        _buffer[_head] = data;

        _head = incrementCounter(_head);

        if (_full) {
            _tail = _head;
        } else if (_head == _tail) {
            _full = true;
        }

        core_util_critical_section_exit();
    }

    /** Push the transaction to the buffer. This overwrites the buffer if it's full.
     *
     * @param src Data to be pushed to the buffer.
     * @param len Number of items to be pushed to the buffer.
     */
    void push(const T *src, CounterType len)
    {
        MBED_ASSERT(len > 0);

        core_util_critical_section_enter();

        /* if we try to write more bytes than the buffer can hold we only bother writing the last bytes */
        if (len > BufferSize) {
            _tail = 0;
            _head = 0;
            _full = true;
            std::copy(src + len - BufferSize, src + len, _buffer);
        } else {
            /* we need to adjust the tail at the end if we're filling the buffer of overflowing */
            bool adjust_tail = ((BufferSize - non_critical_size()) <= len);

            CounterType written = len;

            /* on first pass we write as much as we can to the right of head */
            if ((_head + written) > BufferSize) {
                written = BufferSize - _head;
            }

            std::copy(src, src + written, _buffer + _head);
            _head = incrementCounter(_head, written);

            CounterType left_to_write = len - written;

            /* we might need to continue to write from the start of the buffer */
            if (left_to_write) {
                std::copy(src + written, src + written + left_to_write, _buffer);
                _head = left_to_write;
            }

            if (adjust_tail) {
                _tail = _head;
                _full = true;
            }
        }

        core_util_critical_section_exit();
    }

    /** Push the transaction to the buffer. This overwrites the buffer if it's full.
     *
     * @param src Data to be pushed to the buffer.
     */
    void push(mbed::Span<const T> src)
    {
        push(src.data(), src.size());
    }

    /** Pop from the buffer.
     *
     * @param data Container to store the data to be popped from the buffer.
     * @return True if data popped.
     */
    bool pop(T &data)
    {
        bool data_popped = false;

        core_util_critical_section_enter();

        if (!non_critical_empty()) {
            data_popped = true;

            data = _buffer[_tail];
            _tail = incrementCounter(_tail);
            _full = false;
        }

        core_util_critical_section_exit();

        return data_popped;
    }

    /**
     * Pop multiple elements from the buffer.
     *
     * @param dest The array which will receive the elements.
     * @param len The number of elements to pop.
     *
     * @return The number of elements popped.
     */
    CounterType pop(T *dest, CounterType len)
    {
        MBED_ASSERT(len > 0);

        if (len == 0) {
            return 0;
        }

        CounterType data_popped = 0;

        core_util_critical_section_enter();

        if (!non_critical_empty()) {
            /* make sure we only try to read as much as we have items present */
            if (len > non_critical_size()) {
                len = non_critical_size();
            }
            data_popped = len;

            /* items may be split by overlap, take only the number we have to the right of tail */
            if ((_tail + data_popped) > BufferSize) {
                data_popped = BufferSize - _tail;
            }

            std::copy(_buffer + _tail, _buffer + _tail + data_popped, dest);
            _tail = incrementCounter(_tail, data_popped);

            /* if we looped over the end we may need to pop again */
            CounterType left_to_pop = len - data_popped;

            if (left_to_pop) {
                std::copy(_buffer, _buffer + left_to_pop, dest + data_popped);
                _tail = left_to_pop;

                data_popped += left_to_pop;
            }

            _full = false;
        }

        core_util_critical_section_exit();

        return data_popped;
    }

    /**
     * Pop multiple elements from the buffer.
     *
     * @param dest The span that contains the buffer that will be used to store the elements.
     *
     * @return The span with the size set to number of elements popped using the buffer passed in as the parameter.
     */
    mbed::Span<T> pop(mbed::Span<T> dest)
    {
        CounterType popped = pop(dest.data(), dest.size());
        return mbed::make_Span(dest.data(), popped);
    }

    /** Check if the buffer is empty.
     *
     * @return True if the buffer is empty, false if not.
     */
    bool empty() const
    {
        core_util_critical_section_enter();
        bool is_empty = non_critical_empty();
        core_util_critical_section_exit();
        return is_empty;
    }

    /** Check if the buffer is full.
     *
     * @return True if the buffer is full, false if not
     */
    bool full() const
    {
        return core_util_atomic_load_bool(&_full);
    }

    /**
     * Reset the buffer.
     */
    void reset()
    {
        core_util_critical_section_enter();
        _head = 0;
        _tail = 0;
        _full = false;
        core_util_critical_section_exit();
    }

    /**
     * Get the number of elements currently stored in the circular_buffer.
     */
    CounterType size() const
    {
        core_util_critical_section_enter();
        CounterType elements = non_critical_size();
        core_util_critical_section_exit();
        return elements;
    }

    /** Peek into circular buffer without popping.
     *
     * @param data Data to be peeked from the buffer.
     * @return True if the buffer is not empty and data contains a transaction, false otherwise.
     */
    bool peek(T &data) const
    {
        bool data_updated = false;
        core_util_critical_section_enter();
        if (!empty()) {
            data = _buffer[_tail];
            data_updated = true;
        }
        core_util_critical_section_exit();
        return data_updated;
    }

private:
    bool non_critical_empty() const
    {
        bool is_empty = (_head == _tail) && !_full;
        return is_empty;
    }

    CounterType non_critical_size() const
    {
        CounterType elements;
        if (!_full) {
            if (_head < _tail) {
                elements = BufferSize + _head - _tail;
            } else {
                elements = _head - _tail;
            }
        } else {
            elements = BufferSize;
        }
        return elements;
    }

    /** Used to increment _tail or _head by a given value.
     *
     * @param val The value of the counter to be incremented.
     * @param increment The amount to be added, the value after this incremented must not exceed BufferSize.
     * @return The new value of the counter.
     */
    CounterType incrementCounter(CounterType val, CounterType increment = 1)
    {
        val += increment;

        MBED_ASSERT(val <= BufferSize);

        if (val == BufferSize) {
            val = 0;
        }

        return val;
    }

private:
    T _buffer[BufferSize];
    CounterType _head;
    CounterType _tail;
    bool _full;
};

/**@}*/

/**@}*/

}

#endif