driver.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/shared_ptr.h"
#include "fl/stl/string.h"  // IWYU pragma: keep
#include "fl/stl/noexcept.h"
#include "fl/stl/atomic.h"
 
namespace fl {
 
// Forward declarations
class ChannelData;
FASTLED_SHARED_PTR(ChannelData);

class IChannelDriver {
public:
    struct PollNeededCallback {
        using Callback = void (*)(void*) FL_NOEXCEPT;
 
        Callback callback = nullptr;
        void* context = nullptr;
 
        constexpr PollNeededCallback() FL_NOEXCEPT = default;
        constexpr PollNeededCallback(Callback cb, void* ctx) FL_NOEXCEPT
            : callback(cb), context(ctx) {}
 
        bool isValid() const FL_NOEXCEPT { return callback != nullptr; }
        explicit operator bool() const FL_NOEXCEPT { return isValid(); }
 
        void invoke() const FL_NOEXCEPT {
            if (callback != nullptr) {
                callback(context);
            }
        }
    };

    class PollNeededCallbackSlot {
      private:
        struct Snapshot {
            explicit Snapshot(PollNeededCallback cb) FL_NOEXCEPT
                : callback(cb), next(nullptr) {}
 
            PollNeededCallback callback;
            Snapshot* next;
        };
 
      public:
        PollNeededCallbackSlot() FL_NOEXCEPT
            : mSnapshot(nullptr), mRetired(nullptr) {}
 
        ~PollNeededCallbackSlot() FL_NOEXCEPT {
            Snapshot* active =
                mSnapshot.exchange(nullptr, fl::memory_order_acq_rel);
            destroySnapshots(active);
            destroySnapshots(mRetired);
            mRetired = nullptr;
        }
 
        void set(PollNeededCallback callback) FL_NOEXCEPT {
            if (callback.callback == nullptr) {
                clear();
                return;
            }
            Snapshot* snapshot = new Snapshot(callback); // ok bare allocation
            retire(mSnapshot.exchange(snapshot, fl::memory_order_acq_rel));
        }
 
        void clear() FL_NOEXCEPT {
            retire(mSnapshot.exchange(nullptr, fl::memory_order_acq_rel));
        }
 
        void invoke() const FL_NOEXCEPT {
            Snapshot* snapshot = mSnapshot.load(fl::memory_order_acquire);
            if (snapshot == nullptr) {
                return;
            }
            snapshot->callback.invoke();
        }
 
      private:
        void retire(Snapshot* snapshot) FL_NOEXCEPT {
            if (snapshot == nullptr) {
                return;
            }
            // An ISR may already have loaded this pointer, so reclaim only when
            // the slot is destroyed and driver teardown has quiesced callbacks.
            snapshot->next = mRetired;
            mRetired = snapshot;
        }
 
        static void destroySnapshots(Snapshot* snapshot) FL_NOEXCEPT {
            while (snapshot != nullptr) {
                Snapshot* next = snapshot->next;
                delete snapshot; // ok bare allocation
                snapshot = next;
            }
        }
 
        fl::atomic<Snapshot*> mSnapshot;
        Snapshot* mRetired;
    };

    struct Capabilities {
        bool supportsClockless;  
        bool supportsSpi;        

        constexpr Capabilities() FL_NOEXCEPT : supportsClockless(false), supportsSpi(false) {}

        constexpr Capabilities(bool clockless, bool spi) FL_NOEXCEPT
            : supportsClockless(clockless), supportsSpi(spi) {}
    };

    struct DriverState {
        enum Value {
            READY,      
            BUSY,       
            DRAINING,   
            ERROR,      
        };
 
        Value state;        
        fl::string error;   

        DriverState(Value v) FL_NOEXCEPT : state(v), error() {}

        DriverState(Value v, const fl::string& e) FL_NOEXCEPT : state(v), error(e) {}

        operator Value() const FL_NOEXCEPT { return state; }

        bool operator==(Value v) const FL_NOEXCEPT { return state == v; }
        bool operator!=(Value v) const FL_NOEXCEPT { return state != v; }
    };

    virtual void enqueue(ChannelDataPtr channelData) FL_NOEXCEPT = 0;

    virtual void show() FL_NOEXCEPT = 0;

    virtual DriverState poll() FL_NOEXCEPT = 0;

    virtual fl::string getName() const FL_NOEXCEPT { return fl::string::from_literal(""); }

    virtual Capabilities getCapabilities() const FL_NOEXCEPT = 0;

    virtual bool canHandle(const ChannelDataPtr& data) const FL_NOEXCEPT = 0;

    bool waitForReady(u32 timeoutMs = 1000) FL_NOEXCEPT;
    bool waitForReadyOrDraining(u32 timeoutMs = 1000) FL_NOEXCEPT;

    virtual void setPollNeededCallback(PollNeededCallback callback) FL_NOEXCEPT {
        (void)callback;
    }

    virtual bool waitDone(u32 timeoutMs = 1000) FL_NOEXCEPT {
        return waitForReady(timeoutMs);
    }

    virtual ~IChannelDriver() FL_NOEXCEPT = default;
 
protected:
    IChannelDriver() FL_NOEXCEPT = default;
 
    // Non-copyable, non-movable
    IChannelDriver(const IChannelDriver&) FL_NOEXCEPT = delete;
    IChannelDriver& operator=(const IChannelDriver&) FL_NOEXCEPT = delete;
    IChannelDriver(IChannelDriver&&) FL_NOEXCEPT = delete;
    IChannelDriver& operator=(IChannelDriver&&) FL_NOEXCEPT = delete;
 
    template<typename Condition>
    bool waitForCondition(Condition condition, u32 timeoutMs = 1000) FL_NOEXCEPT;
};
 
}  // namespace fl