multi_buffer.h

Go to the documentation of this file.

// Copyright 2024-2025 The Aerospace Corporation.
// This file is a part of SatCat5, licensed under CERN-OHL-W v2 or later.
 
#pragma once
 
#include <satcat5/io_readable.h>
#include <satcat5/io_writeable.h>
#include <satcat5/list.h>
#include <satcat5/types.h>
 
// Set default: Chunk size for internal allocator.
#ifndef SATCAT5_MBUFF_CHUNK
#define SATCAT5_MBUFF_CHUNK     (64 - sizeof(uintptr_t))
#endif
 
// Set default: Maximum bytes per packet.
#ifndef SATCAT5_MBUFF_PKTLEN
#define SATCAT5_MBUFF_PKTLEN    2048
#endif
 
// Set default: Maximum packets in the read queue.
#ifndef SATCAT5_MBUFF_RXPKT
#define SATCAT5_MBUFF_RXPKT     32
#endif
 
// Set default: Per-byte read timeout, in milliseconds.
#ifndef SATCAT5_MBUFF_TIMEOUT
#define SATCAT5_MBUFF_TIMEOUT   1500
#endif
 
// Set default: Reserved size for additional packet metadata.
#ifndef SATCAT5_MBUFF_USER
#define SATCAT5_MBUFF_USER      8
#endif
 
namespace satcat5 {
    namespace io {
        struct MultiChunk final {
        private:
            friend satcat5::util::ListCore;
            satcat5::io::MultiChunk* m_next;
        public:
            constexpr MultiChunk() : m_next(0), m_data{0} {}
            MultiChunk(const MultiChunk& t) = delete;
            MultiChunk& operator=(const MultiChunk& t) = delete;
            u8 m_data[SATCAT5_MBUFF_CHUNK];
        };
 
        struct MultiPacket final {
        private:
            friend satcat5::util::ListCore;
            satcat5::io::MultiPacket* m_next;
 
        public:
            // Data for this packet should only be read by io::MultiReader.
            satcat5::util::List<satcat5::io::MultiChunk> m_chunks;
            unsigned m_length;                  
            unsigned m_refct;                   
            u16 m_priority;                     
            u16 m_pcount;                       
            // Metadata for user extensions (see comment above).
            u32 m_user[SATCAT5_MBUFF_USER];     
 
            // Explicitly declare default constructor and copy operators.
            MultiPacket() = default;
            MultiPacket(const MultiChunk& t) = delete;
            MultiPacket& operator=(const MultiChunk& t) = delete;
 
            inline bool is_deleted() const
                { return m_length && m_chunks.is_empty(); }
 
            satcat5::io::ArrayRead peek() const;
 
            bool copy_to(satcat5::io::Writeable* wr) const;
 
            class Reader : public satcat5::io::Readable {
            public:
                explicit Reader(const satcat5::io::MultiPacket* pkt = 0);
 
                inline satcat5::io::MultiPacket* get_packet() const
                    { return (MultiPacket*)m_read_pkt; }
 
                void read_reset(const satcat5::io::MultiPacket* pkt);
 
                // Implement the io::Readable API.
                // (Inherits Doxygen comments from io_writeable.h.)
                unsigned get_read_ready() const override;
                bool read_bytes(unsigned nbytes, void* dst) override;
                bool read_consume(unsigned nbytes) override;
                void read_finalize() override;
 
            protected:
                // Implement the io::Readable API.
                u8 read_next() override;
 
            private:
                unsigned m_read_pos;
                unsigned m_read_rem;
                const satcat5::io::MultiPacket* m_read_pkt;
                satcat5::io::MultiChunk* m_read_chunk;
            };
 
            class Overwriter : public satcat5::io::Writeable {
            public:
                explicit Overwriter(satcat5::io::MultiPacket* pkt);
 
                inline unsigned write_count() const {return m_write_tot;}
 
                // Implement the io::Writeable API.
                // (Inherits Doxygen comments from io_writeable.h.)
                unsigned get_write_space() const override;
                void write_bytes(unsigned nbytes, const void* src) override;
 
            protected:
                // Implement the io::Writeable API.
                void write_next(u8 data) override;
 
            private:
                unsigned m_write_pos;
                unsigned m_write_rem;
                unsigned m_write_tot;
                satcat5::io::MultiChunk* m_write_chunk;
            };
        };
 
        class MultiBuffer : protected satcat5::poll::OnDemand {
        public:
            MultiBuffer(u8* buff, unsigned nbytes);
 
            bool consistency() const;
 
            inline unsigned get_free_bytes() const
                { return m_free_bytes; }
 
            inline u16 get_pcount()
                { return m_pcount; }
 
            bool enqueue(satcat5::io::MultiPacket* packet);
 
            void free_packet(satcat5::io::MultiPacket* packet);
 
        protected:
            satcat5::io::MultiPacket* dequeue();
            void poll_demand() override;
 
            virtual unsigned deliver(satcat5::io::MultiPacket* packet);
 
            satcat5::io::MultiChunk* new_chunk();
            satcat5::io::MultiPacket* new_packet();
 
            // Internal state.
            friend satcat5::io::MultiReader;
            friend satcat5::io::MultiWriter;
            unsigned m_free_bytes;
            u16 m_pcount;
            satcat5::util::List<satcat5::io::MultiChunk> m_free_chunks;
            satcat5::util::List<satcat5::io::MultiReader> m_read_ports;
            satcat5::util::List<satcat5::io::MultiPacket> m_rcvd_packets;
        };
 
        class MultiReader
            : public satcat5::io::MultiPacket::Reader
            , public satcat5::poll::Timer
        {
        public:
            virtual bool accept(satcat5::io::MultiPacket* packet);
 
            void flush();
 
            bool get_port_enable() const
                { return m_port_enable; }
 
            void set_port_enable(bool enable)
                { m_port_enable = enable; }
 
            inline void set_timeout(unsigned timeout_msec)
                { m_read_timeout = timeout_msec; }
 
            // Override the basic read_finalize() behavior.
            void read_finalize() override;
 
        protected:
            explicit MultiReader(satcat5::io::MultiBuffer* src);
            ~MultiReader() SATCAT5_OPTIONAL_DTOR;
 
            virtual bool pkt_push(satcat5::io::MultiPacket* packet) = 0;
 
            virtual satcat5::io::MultiPacket* pkt_pop() = 0;
 
            void pkt_init(satcat5::io::MultiPacket* packet);
 
            void pkt_free(satcat5::io::MultiPacket* packet);
 
            void timer_event() override;
 
            satcat5::io::MultiBuffer* const m_src;
 
            friend satcat5::util::ListCore;
            satcat5::io::MultiReader* m_next;
 
            bool m_port_enable;
            unsigned m_read_timeout;
        };
 
        class MultiReaderSimple : public satcat5::io::MultiReader {
        public:
            explicit MultiReaderSimple(satcat5::io::MultiBuffer* src);
            ~MultiReaderSimple() SATCAT5_OPTIONAL_DTOR;
 
            inline bool can_accept() const
                { return m_queue_count < SATCAT5_MBUFF_RXPKT; }
 
        protected:
            bool pkt_push(satcat5::io::MultiPacket* pkt) override;
            satcat5::io::MultiPacket* pkt_pop() override;
 
        private:
            unsigned m_queue_rdidx;
            unsigned m_queue_count;
            satcat5::io::MultiPacket* m_queue[SATCAT5_MBUFF_RXPKT];
        };
 
        class MultiReaderPriority : public satcat5::io::MultiReader {
        public:
            explicit MultiReaderPriority(satcat5::io::MultiBuffer* src);
            ~MultiReaderPriority() SATCAT5_OPTIONAL_DTOR;
 
            inline bool can_accept() const
                { return m_heap_count < SATCAT5_MBUFF_RXPKT; }
 
            bool consistency() const;
 
        protected:
            bool pkt_push(satcat5::io::MultiPacket* pkt) override;
            satcat5::io::MultiPacket* pkt_pop() override;
 
        private:
            u32 offset_priority(unsigned idx) const;
 
            unsigned swap_index(unsigned prev, unsigned next);
 
            unsigned m_heap_count;
            satcat5::io::MultiPacket* m_heap[SATCAT5_MBUFF_RXPKT];
        };
 
        class MultiWriter
            : public satcat5::io::Writeable
            , public satcat5::poll::Timer
        {
        public:
            explicit MultiWriter(satcat5::io::MultiBuffer* dst);
            ~MultiWriter() SATCAT5_OPTIONAL_DTOR;
 
            inline void set_max_packet(unsigned max_bytes)
                { m_write_maxlen = max_bytes; }
 
            void set_priority(u16 priority);
 
            inline void set_timeout(unsigned timeout_msec)
                { m_write_timeout = timeout_msec; }
 
            inline unsigned get_write_partial() const {return m_write_len;}
 
            // Implement the io::Writeable API.
            // (Inherits Doxygen comments from io_writeable.h.)
            unsigned get_write_space() const override;
            void write_bytes(unsigned nbytes, const void* src) override;
            void write_abort() override;
            bool write_finalize() override;
 
            bool write_bypass(satcat5::io::MultiReader* dst);
 
        protected:
            void timer_event() override;
 
            // Implement the io::Writeable API.
            // (Inherits Doxygen comments from io_writeable.h.)
            void write_next(u8 data) override;
            void write_overflow() override;
 
            unsigned write_prep();
 
            satcat5::io::MultiPacket* prepare_pkt();
 
            satcat5::io::MultiBuffer* const m_dst;
 
            satcat5::io::MultiPacket* m_write_pkt;
            satcat5::io::MultiChunk* m_write_tail;
            unsigned m_write_pos;
            unsigned m_write_len;
            unsigned m_write_maxlen;
            unsigned m_write_timeout;
        };
 
        class MultiWriterBypass : public MultiWriter {
        public:
            MultiWriterBypass(
                satcat5::io::MultiBuffer* buf,
                satcat5::io::MultiReader* dst,
                u16 priority = 0);
 
            bool write_finalize() override;
 
        protected:
            satcat5::io::MultiReader* const m_dst;
            u16 m_priority;
        };
    }
}