metro()

MAYAFLUX_API std::shared_ptr< Vruta::Routine > MayaFlux::Kriya::metro	(	double	interval_seconds,
		std::function< void()>	callback,
		Vruta::ProcessingToken	token = Vruta::ProcessingToken::SAMPLE_ACCURATE
	)

Creates a periodic event generator that executes a callback at regular intervals.

Parameters

interval_seconds	Time between callback executions in seconds
callback	Function to execute on each interval
token	Processing token to determine which scheduler rate to use (default: SAMPLE_ACCURATE)

Returns

A Routine shared_ptr of type determined by the processing token of the scheduler (SoundRoutine, GraphicsRoutine, etc.)

The metro task provides a fundamental temporal mechanism for creating time-based structures in computational systems. It executes the provided callback function at precise, regular intervals with sample-accurate timing, enabling the creation of rhythmic patterns, event sequences, and temporal frameworks that can synchronize across different domains.

Unlike system timers which can drift due to processing load, this implementation maintains precise timing by synchronizing with the sample-rate clock, making it suitable for both audio and cross-domain applications where timing accuracy is critical.

Example usage:

// Create a periodic event generator (2Hz)
auto periodic_task = Kriya::metro(0.5, []() {
    trigger_event(); // Could affect audio, visuals, data, etc.
});
scheduler->add_task(periodic_task);

The metro task continues indefinitely until explicitly cancelled, creating a persistent temporal structure within the computational system.

Definition at line 12 of file Tasks.cpp.

{
    if (token == Vruta::ProcessingToken::FRAME_ACCURATE) {
        auto coro = [](double interval, std::function<void()> cb) -> Vruta::GraphicsRoutine {
            uint64_t units = Vruta::seconds_to_frames(interval);
            if (units < 1) {
                MF_RT_WARN(Journal::Component::Kriya, Journal::Context::CoroutineScheduling,
                    "metro interval {}s is shorter than one frame, clamping to 1 frame", interval);
            }
            units = std::max<uint64_t>(1, units);
            auto& p = co_await GetGraphicsPromise {};
            while (!p.should_terminate) {
                cb();
                co_await FrameDelay { .frames_to_wait = units };
            }
        };
        return std::make_shared<Vruta::GraphicsRoutine>(coro(interval_seconds, std::move(callback)));
    }
    auto coro = [](double interval, std::function<void()> cb) -> Vruta::SoundRoutine {
        uint64_t units = Vruta::seconds_to_samples(interval);
        if (units < 1) {
            MF_RT_WARN(Journal::Component::Kriya, Journal::Context::CoroutineScheduling,
                "metro interval {}s is shorter than one sample, clamping to 1 sample", interval);
        }
        units = std::max<uint64_t>(1, units);
        auto& p = co_await GetAudioPromise {};
        while (!p.should_terminate) {
            cb();
            co_await SampleDelay { units };
        }
    };
    return std::make_shared<Vruta::SoundRoutine>(coro(interval_seconds, std::move(callback)));
}

References callback, MayaFlux::Journal::CoroutineScheduling, MayaFlux::Vruta::FRAME_ACCURATE, MayaFlux::Kriya::FrameDelay::frames_to_wait, MayaFlux::Journal::Kriya, MF_RT_WARN, MayaFlux::Vruta::seconds_to_frames(), and MayaFlux::Vruta::seconds_to_samples().

Referenced by MayaFlux::Nexus::Wiring::finalise(), and MayaFlux::schedule_metro().

Here is the call graph for this function:

Here is the caller graph for this function: