generation_routing.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/platform/device_capability.hpp>
 
#include <cstddef>
#include <cstdint>
 
namespace pulp::format {

enum class GenerationJobClass : std::uint8_t {
    ProposalGeneration = 0,
    ArtifactPlayback = 1,
    ReceiptRendering = 2,
};
 
inline constexpr std::size_t kGenerationJobClassCount = 3;

enum class GenerationRoute : std::uint8_t {
    OnDevice = 0,
    Server = 1,
    QueueForLater = 2,
};
 
inline constexpr std::size_t kGenerationRouteCount = 3;

enum class GenerationHostContext : std::uint8_t {
    Standalone = 0,
    AudioUnitV3 = 1,
};
 
inline constexpr std::size_t kGenerationHostContextCount = 2;

enum class GenerationConnectivity : std::uint8_t {
    Online = 0,
    Offline = 1,
};
 
inline constexpr std::size_t kGenerationConnectivityCount = 2;
 
namespace detail {

inline constexpr GenerationRoute
    kProposalRouteTable[platform::kDeviceCapabilityTierCount][platform::kThermalStateCount] = {
        // Constrained: never local. The rung is defined as review-and-perform
        // with no local realtime, so inference is out at every temperature.
        {GenerationRoute::Server, GenerationRoute::Server, GenerationRoute::Server,
         GenerationRoute::QueueForLater},
        // Standard: authoring-complete, but inference is not part of that
        // promise, so it offloads at every temperature it can reach a server at.
        {GenerationRoute::Server, GenerationRoute::Server, GenerationRoute::Server,
         GenerationRoute::QueueForLater},
        // Full: precision authoring with headroom — the only rung that spends
        // its own cycles on a proposal, and only while it is cool enough to.
        {GenerationRoute::OnDevice, GenerationRoute::Server, GenerationRoute::Server,
         GenerationRoute::QueueForLater},
};
 
} // namespace detail

[[nodiscard]] constexpr GenerationRoute
generation_route(platform::DeviceCapabilityTier tier, platform::ThermalState thermal,
                 GenerationJobClass job, GenerationHostContext context,
                 GenerationConnectivity connectivity) noexcept {
    const auto tier_index = static_cast<std::size_t>(tier);
    const auto thermal_index = static_cast<std::size_t>(thermal);
    const auto job_index = static_cast<std::size_t>(job);
    const auto context_index = static_cast<std::size_t>(context);
    const auto connectivity_index = static_cast<std::size_t>(connectivity);
    if (tier_index >= platform::kDeviceCapabilityTierCount ||
        thermal_index >= platform::kThermalStateCount ||
        job_index >= kGenerationJobClassCount ||
        context_index >= kGenerationHostContextCount ||
        connectivity_index >= kGenerationConnectivityCount) {
        // No unrecognized discriminator may select local or server work. This
        // also makes extending any vocabulary fail closed until the routing
        // policy explicitly adopts the new value.
        return GenerationRoute::QueueForLater;
    }
 
    // Playing an existing artifact and rendering a receipt are local work that
    // needs no server and must survive every degradation. Answering them first
    // keeps them out of reach of the connectivity and thermal rules below.
    if (job != GenerationJobClass::ProposalGeneration) {
        return GenerationRoute::OnDevice;
    }
 
    // Offline outranks the table: with no server reachable, the only honest
    // answers are "run it here" or "hold it", and an AUv3 may not run it here.
    if (connectivity == GenerationConnectivity::Offline) {
        const auto local = tier == platform::DeviceCapabilityTier::Full &&
                           thermal == platform::ThermalState::Nominal &&
                           context == GenerationHostContext::Standalone;
        return local ? GenerationRoute::OnDevice : GenerationRoute::QueueForLater;
    }
 
    const auto route = detail::kProposalRouteTable[tier_index][thermal_index];
 
    // An AUv3 never spends its host's memory budget on inference, whatever the
    // table says. This is a hard substitution rather than a separate table so
    // that no future edit to the table can accidentally grant it.
    if (context == GenerationHostContext::AudioUnitV3 && route == GenerationRoute::OnDevice) {
        return GenerationRoute::Server;
    }
    return route;
}

[[nodiscard]] constexpr bool runs_inference_on_device(GenerationJobClass job,
                                                      GenerationRoute route) noexcept {
    return job == GenerationJobClass::ProposalGeneration && route == GenerationRoute::OnDevice;
}
 
} // namespace pulp::format