triple_buffer

/*
Copyright (C) 2018-2024 Geoffrey Daniels. https://gpdaniels.com/

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, version 3 of the License only.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.
*/

#pragma once
#ifndef GTL_EXECUTION_TRIPLE_BUFFER_HPP
#define GTL_EXECUTION_TRIPLE_BUFFER_HPP

// Summary: Lockless triple buffer interface to three buffers.

#if defined(_MSC_VER)
#   pragma warning(push, 0)
#endif

#include <atomic>

#if defined(_MSC_VER)
#   pragma warning(pop)
#endif

namespace gtl {
    /// @brief  The triple_buffer class implements a thread-safe single-producer single-consumer triple-buffer.
    template<typename buffer_type>
    class triple_buffer final {
    public:
        /// @brief  Make the buffer type publically accessible.
        using type = buffer_type;

    private:
        /// @brief  Structure that holds the index of the read, swap and write buffers, and a flag that is set on write.
        struct index_type final {
            unsigned char read : 2;
            unsigned char swap : 2;
            unsigned char write : 2;
            unsigned char updated : 2;
        };

        static_assert(sizeof(index_type) == 1, "The size of the index_type is assumed to be one byte.");

    private:
        /// @brief  An atomic index using the index_type to index into the buffers array;
        std::atomic<index_type> indexes;

        /// @brief  The buffers.
        buffer_type buffers[3];

    public:
        /// @brief  Defaulted destructor.
        ~triple_buffer() = default;

        /// @brief  Constructor initialises the atomic indexes.
        triple_buffer() {
            this->indexes.store(index_type{0, 1, 2, 0});
        }

        /// @brief  Deleted copy constructor.
        triple_buffer(const triple_buffer&) = delete;

        /// @brief  Defaulted move constructor.
        triple_buffer(triple_buffer&&) = default;

        /// @brief  Deleted copy asignement operator.
        triple_buffer& operator=(const triple_buffer&) = delete;

        /// @brief  Defaulted move asignement operator.
        triple_buffer& operator=(triple_buffer&&) = default;

        /// @brief  Update the read buffer location if newer data is available in the swap buffer.
        /// @return true if the read buffer location was updated, false otherwise.
        bool update_read() {
            // Set the atomic flag to mark the read buffer as holding the latest data.
            if (this->indexes.load().updated > 0) {
                // Get the current indexes.
                index_type current_indexes = this->indexes.load();

                // Try repeatably to exchange the swap and read indexes and set the updated flag to 0.
                while (!std::atomic_compare_exchange_weak(&this->indexes, &current_indexes, index_type{ current_indexes.swap, current_indexes.read, current_indexes.write, 0 }));

                // Return true to notify that the buffers were swapped.
                return true;
            }
            // Return false to notify that the buffers were not swapped.
            return false;
        }

        /// @brief  Get a reference to the read buffer.
        /// @return A reference to the read buffer.
        type& get_read() {
            return this->buffers[this->indexes.load().read];
        }

        /// @brief  Get a reference to the write buffer.
        /// @return A reference to the write buffer.
        type& get_write() {
            return this->buffers[this->indexes.load().write];
        }

        /// @brief  Update the write buffer location to the swap buffer.
        void update_write() {
            // Get the current indexes.
            index_type current_indexes = this->indexes.load();

            // Try repeatably to exchange the write and swap indexes.
            while (!std::atomic_compare_exchange_weak(&this->indexes, &current_indexes, index_type{ current_indexes.read, current_indexes.write, current_indexes.swap, 1 }));
        }
    };
}

#endif // GTL_EXECUTION_TRIPLE_BUFFER_HPP