pacinggate.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_CORE
#include <promeki/namespace.h>
#include <promeki/clock.h>
#include <promeki/duration.h>
#include <promeki/error.h>
#include <promeki/mediatimestamp.h>
 
PROMEKI_NAMESPACE_BEGIN
 
enum class PacingVerdict {
        OnTime,
        Late,
        Skip,
        Reanchor,
};
 
struct PacingResult {
                PacingVerdict verdict = PacingVerdict::OnTime;
 
                Duration slack;
 
                int skippedTicks = 0;
 
                Error error = Error::Ok;
};
 
class PacingGate {
        public:
                static constexpr int DefaultReanchorMultiple = 8;
 
                PacingGate() = default;
 
                explicit PacingGate(const Clock::Ptr &clock, const Duration &period = Duration::zero());
 
                // ---- Configuration ----
 
                void               setClock(const Clock::Ptr &clock);
 
                const Clock::Ptr  &clock() const { return _clock; }
 
                bool               hasClock() const { return _clock.isValid(); }
 
                void               setPeriod(const Duration &period);
 
                const Duration    &period() const { return _period; }
 
                void               setSkipThreshold(const Duration &t);
 
                const Duration    &skipThreshold() const { return _skipThreshold; }
 
                void               setReanchorThreshold(const Duration &t);
 
                const Duration    &reanchorThreshold() const { return _reanchorThreshold; }
 
                void               rearm();
 
                // ---- Wait ----
 
                PacingResult       wait(const Duration &advance);
 
                PacingResult       wait() { return wait(_period); }
 
                bool               tryAcquire(const Duration &advance);
 
                bool               tryAcquire() { return tryAcquire(_period); }
 
                // ---- Telemetry ----
 
                int64_t            ticksOnTime() const { return _ticksOnTime; }
 
                int64_t            ticksLate() const { return _ticksLate; }
 
                int64_t            ticksSkipped() const { return _ticksSkipped; }
 
                int64_t            reanchors() const { return _reanchors; }
 
                int64_t            tryAcquireRejected() const { return _tryAcquireRejected; }
 
                bool               isArmed() const { return _armed; }
 
                const MediaTimeStamp &anchor() const { return _anchor; }
 
                const Duration &accumulated() const { return _accumulated; }
 
        private:
                Clock::Ptr     _clock;
                // _period defaults to zero so the documented
                // "defaults to zero — the no-arg @ref wait is a
                // no-op" contract still holds for callers that
                // don't supply a period at construction.
                Duration       _period = Duration::zero();
                Duration       _skipThreshold = Duration::zero();
                Duration       _reanchorThreshold = Duration::zero();
                MediaTimeStamp _anchor;
                // _accumulated is incremented per wait() — start at
                // an explicit zero so the first += produces a valid
                // sum (rather than invalid + valid = invalid).
                Duration       _accumulated = Duration::zero();
                bool           _armed = false;
                bool           _customSkipThreshold = false;
                bool           _customReanchorThreshold = false;
                int64_t        _ticksOnTime = 0;
                int64_t        _ticksLate = 0;
                int64_t        _ticksSkipped = 0;
                int64_t        _reanchors = 0;
                int64_t        _tryAcquireRejected = 0;
};
 
PROMEKI_NAMESPACE_END
 
#endif // PROMEKI_ENABLE_CORE