salmanoff/include/user/stimulusBuffer.h

#ifndef _STIMULUS_BUFFER_H
#define _STIMULUS_BUFFER_H

#include <boostAsioLinkageFix.h>
#include <vector>
#include <memory>
#include <cstdint>
#include <atomic>
#include <mutex>
#include <functional>
#include <iostream>
#include <chrono>
#include <config.h>
#include <boost/asio/io_service.hpp>
#include <boost/asio/deadline_timer.hpp>
#include <spinLock.h>
#include <user/spMcRingBuffer.h>
#include "stimulusFrame.h"
#include "deviceAttachmentSpec.h"

namespace smo {
namespace stim_buff {

/**
 * StimulusBuffer manages a collection of stimulus frames with simultaneity stamps.
 *
 * This buffer is designed to hold stimulus frames that have been assembled
 * from raw sensor data (e.g., Livox Avia point cloud data) and are ready
 * for processing by the mind layer.
 *
 * The buffer provides thread-safe operations for adding frames, retrieving
 * frames, and managing the buffer state.
 */
class StimulusBuffer
{
public:
	class PcloudFormatDesc
	{
	public:
		enum class Format
		{
			XYZ,
			XYZI,
		};

	public:
		Format format;
	};

public:
	explicit StimulusBuffer(
		const std::shared_ptr<device::DeviceAttachmentSpec>
			&deviceAttachmentSpec,
		size_t nSlots,
		const SpMcRingBuffer::InputEngineConstraints& ringBufferConstraints,
		boost::asio::io_service& ioService_)
	: deviceAttachmentSpec(deviceAttachmentSpec),
	ringBuffer(nSlots, ringBufferConstraints),
	ioService(ioService_),
	shouldContinue(false), timer(ioService),
	nDeferrals(0)
	{}

	virtual ~StimulusBuffer() = default;

	// Non-copyable, movable
	StimulusBuffer(const StimulusBuffer&) = delete;
	StimulusBuffer& operator=(const StimulusBuffer&) = delete;
	StimulusBuffer(StimulusBuffer&&) = default;
	StimulusBuffer& operator=(StimulusBuffer&&) = default;

	// Control methods
	virtual void start()
	{
		std::cout << __func__ << ": Starting stimulus buffer for device "
			<< deviceAttachmentSpec->deviceSelector << std::endl;

		shouldContinue = true;
		nDeferrals = 0;
		scheduleNextTimeout();
	}

	virtual void stop();

	void allowNextStimulusFrame()
		{ frameAssemblyRateLimiter.release(); }

protected:
	// Virtual functions for derived classes to override
	virtual int getStopDelayMs() const
	{
		return CONFIG_STIMBUFF_FRAME_PERIOD_MS;
	}

	virtual void stimFrameProductionTimesliceInd() = 0;

private:
	void onTimeout(const boost::system::error_code& error);

public:
	std::shared_ptr<device::DeviceAttachmentSpec> deviceAttachmentSpec;
	std::vector<StimulusFrame> frames_;

protected:
	SpinLock frameAssemblyRateLimiter;
	SpMcRingBuffer ringBuffer;

private:
	boost::asio::io_service& ioService;
protected:
	SpinLock shouldContinueLock;
	bool shouldContinue;
private:
	boost::asio::deadline_timer timer;
	size_t nDeferrals;
	std::chrono::high_resolution_clock::time_point deferralStartTime;

	void scheduleNextTimeout(int delayMs = CONFIG_STIMBUFF_FRAME_PERIOD_MS);
};

} // namespace stim_buff
} // namespace smo

#endif // _STIMULUS_BUFFER_H