compile_context_registry.hpp

Go to the documentation of this file.

#pragma once
 
#include <pulp/playback/dirty_track_resolver.hpp>
#include <pulp/runtime/result.hpp>
#include <pulp/timeline/compile_context.hpp>
#include <pulp/timeline/production_mode.hpp>
#include <pulp/timeline/schema_registry.hpp>
#include <pulp/timeline/transaction.hpp>
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::playback {
 
namespace detail {
struct CompileInvalidationData;
struct ContextRegistryGeneration;
} // namespace detail

enum class ContentProgramOutputKind : std::uint8_t { Notes };

enum class RegisteredRendererStatePolicy : std::uint8_t { Reset, CarryByItemId };

struct ContentFragmentNote {
    timebase::TickPosition start;
    timebase::TickDuration duration;
    std::uint16_t velocity = 0xffff;
    std::uint8_t pitch = 60;
    std::uint8_t channel = 0;
    constexpr auto operator<=>(const ContentFragmentNote&) const = default;
};
 
enum class ContentFragmentErrorCode : std::uint8_t {
    RendererFailed,
    InvalidNote,
};
 
struct ContentFragmentError {
    ContentFragmentErrorCode code = ContentFragmentErrorCode::RendererFailed;
    std::size_t note_index = 0;
};

class ContentProgramFragment {
  public:
    static runtime::Result<ContentProgramFragment, ContentFragmentError>
    create(std::vector<ContentFragmentNote> notes, timebase::TickDuration clip_duration) noexcept;
 
    std::span<const ContentFragmentNote> notes() const noexcept {
        return *notes_;
    }
 
  private:
    explicit ContentProgramFragment(
        std::shared_ptr<const std::vector<ContentFragmentNote>> notes) noexcept
        : notes_(std::move(notes)) {}
    std::shared_ptr<const std::vector<ContentFragmentNote>> notes_;
};

struct RegisteredContentCompileInput {
    const timeline::RegisteredContent& content;
    timeline::ItemId clip_id;
    timebase::TickDuration clip_duration;
    timebase::TickPosition context_start;
    timeline::CompileContextView context;
    std::size_t maximum_fragment_notes = 0;
};
 
// A hook invocation is one trusted atomic compile work unit: it must not block
// or perform unbounded work, and it must honor maximum_fragment_notes. The
// compiler checks the returned size before admission; the registry-wide 4096
// ceiling bounds valid fragment construction even though arbitrary hook code
// cannot be preempted from inside this function-pointer ABI.
using RegisteredContentCompileFn =
    runtime::Result<ContentProgramFragment, ContentFragmentError> (*)(
        const RegisteredContentCompileInput& input, const void* context) noexcept;

struct ContentRendererRegistration {
    std::string content_type_name;
    timeline::CompileContextSubscriptions subscriptions;
    // Zero plus a null hook is the legacy subscription-only declaration. It is
    // intentionally unresolved at compile time, not silently rendered.
    std::uint32_t schema_version = 0;
    ContentProgramOutputKind output_kind = ContentProgramOutputKind::Notes;
    std::size_t maximum_fragment_notes = 0;
    RegisteredRendererStatePolicy state_policy = RegisteredRendererStatePolicy::Reset;
    timeline::ProductionDeclaration production;
    std::shared_ptr<const void> compile_context;
    RegisteredContentCompileFn compile = nullptr;
    // Filled by the validated declare overload. Dispatch compares this opaque
    // codec provenance with RegisteredContent before any value_as<T>() call.
    std::shared_ptr<const void> schema_registry_identity;
};
 
enum class ContextRegistrationErrorCode : std::uint8_t {
    EmptyContentTypeName,
    DuplicateContentType,
    CapacityExceeded,
    InvalidSchemaVersion,
    SchemaUnavailable,
    SchemaCodecUnavailable,
    InvalidFragmentQuota,
    InvalidProductionDeclaration,
    MissingCompileHook,
    InvalidOutputKind,
    InvalidStatePolicy,
};
 
struct ContextRegistrationError {
    ContextRegistrationErrorCode code = ContextRegistrationErrorCode::EmptyContentTypeName;
    std::string content_type_name;
};

class CompileContextRegistry {
  public:
    static constexpr std::size_t kMaxRegistrations = 1024;
    static constexpr std::size_t kMaximumFragmentNotesPerClip = 4096;
 
    CompileContextRegistry();
    CompileContextRegistry(const CompileContextRegistry& other);
    CompileContextRegistry(CompileContextRegistry&& other);
    CompileContextRegistry& operator=(const CompileContextRegistry& other);
    CompileContextRegistry& operator=(CompileContextRegistry&& other);

    std::optional<ContextRegistrationError> declare(ContentRendererRegistration registration);

    std::optional<ContextRegistrationError> declare(ContentRendererRegistration registration,
                                                    const timeline::SchemaRegistry& schemas);

    timeline::CompileContextSubscriptions
    subscriptions_for(std::string_view content_type_name) const noexcept;

    const ContentRendererRegistration* find(const timeline::SchemaIdentity& schema) const noexcept;
    const ContentRendererRegistration*
    find(const timeline::RegisteredContent& content) const noexcept;
 
    std::size_t size() const noexcept {
        return registrations_.size();
    }

    std::uint64_t revision() const noexcept;
    std::shared_ptr<const void> generation_identity() const noexcept {
        return snapshot_generation_ ? snapshot_generation_ : generation_;
    }
 
  private:
    friend class CompileInvalidationIndex;
    friend class PlaybackProgramCompiler;
    friend struct CompileInvalidationInput;

    std::shared_ptr<const CompileContextRegistry> immutable_snapshot() const;
 
    // Sorted by content_type_name so lookup is a binary search on a hot path.
    std::vector<ContentRendererRegistration> registrations_;
    std::shared_ptr<detail::ContextRegistryGeneration> generation_;
    std::shared_ptr<const detail::ContextRegistryGeneration> snapshot_generation_;
    std::optional<std::uint64_t> snapshot_revision_;
};

class CompileInvalidationIndex {
  public:
    static CompileInvalidationIndex build(const timeline::Project& project,
                                          timeline::ItemId sequence_id,
                                          const CompileContextRegistry& registry);

    std::span<const timeline::ItemId> subscribers(timeline::CompileContextKind kind) const noexcept;

    std::span<const timeline::ItemId> subscribers(timeline::ItemId owner_sequence,
                                                  timeline::CompileContextKind kind) const noexcept;
 
    bool empty() const noexcept;
 
    bool valid() const noexcept;
    bool matches(const timeline::Project& project,
                 timeline::ItemId root_sequence_id) const noexcept;
 
  private:
    friend DirtyTrackSet resolve_dirty_tracks(const timeline::Project&, timeline::ItemId,
                                              const timeline::DirtySet&,
                                              const CompileInvalidationIndex&);
 
    std::shared_ptr<const detail::CompileInvalidationData> data_;
};
 
} // namespace pulp::playback