BufferUtils.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/Core/ProcessingTokens.hpp"
 
namespace MayaFlux::Buffers {
 
/**
 * @enum TokenEnforcementStrategy
 * @brief Defines how strictly processing token requirements are enforced in buffer processing chains
 *
 * TokenEnforcementStrategy provides different levels of flexibility for handling processor-buffer
 * compatibility based on processing tokens. This allows the system to balance performance optimization
 * with operational flexibility depending on the application's requirements.
 *
 * The enforcement strategy affects how BufferProcessingChain handles processors with incompatible
 * tokens, ranging from strict validation to complete flexibility. This enables different operational
 * modes for development, production, and specialized processing scenarios.
 */
enum class TokenEnforcementStrategy {
    /**
     * @brief Strictly enforces token assignment with no cross-token sharing
     *
     * Processors must exactly match the buffer's processing token requirements.
     * Any incompatibility results in immediate rejection. This provides maximum
     * performance optimization by ensuring all processors in a chain can execute
     * with the same backend configuration, but offers the least flexibility.
     */
    STRICT,
 
    /**
     * @brief Filters processors through token enumeration, allowing compatible combinations
     *
     * Uses the are_tokens_compatible() function to determine if processors can work
     * together despite different token assignments. This allows some flexibility while
     * maintaining performance optimization for compatible processor combinations.
     * Incompatible processors are filtered out rather than rejected outright.
     */
    FILTERED,
 
    /**
     * @brief Allows token overrides but skips processing for incompatible operations
     *
     * Permits processors with different tokens to be added to processing chains,
     * but skips their execution when the tokens are incompatible. This maintains
     * chain integrity while allowing dynamic processor management. Useful for
     * conditional processing scenarios where not all processors need to execute.
     */
    OVERRIDE_SKIP,
 
    /**
     * @brief Allows token overrides but rejects incompatible processors from chains
     *
     * Similar to OVERRIDE_SKIP but removes incompatible processors from the chain
     * entirely rather than skipping them. This provides a middle ground between
     * flexibility and performance by cleaning up incompatible processors while
     * allowing initial token mismatches during chain construction.
     */
    OVERRIDE_REJECT,
 
    /**
     * @brief Ignores token assignments completely, allowing any processing combination
     *
     * Disables all token validation and compatibility checking. Any processor can
     * be added to any buffer's processing chain regardless of token compatibility.
     * This provides maximum flexibility but may result in suboptimal performance
     * or execution errors. Primarily useful for debugging or specialized scenarios.
     */
    IGNORE
};
 
/**
 * @brief Validates that a processing token has a valid, non-conflicting configuration
 * @param token Processing token to validate
 * @throws std::invalid_argument if the token contains mutually exclusive flags
 *
 * This function ensures that processing tokens contain only compatible flag combinations.
 * It validates three key mutual exclusions that are fundamental to the processing model:
 *
 * **Rate Mutual Exclusion**: SAMPLE_RATE and FRAME_RATE cannot be combined as they
 * represent fundamentally different temporal processing models that cannot be executed
 * simultaneously within the same processing context.
 *
 * **Device Mutual Exclusion**: CPU_PROCESS and GPU_PROCESS cannot be combined as they
 * represent different execution environments that require different resource allocation
 * and execution strategies.
 *
 * **Concurrency Mutual Exclusion**: SEQUENTIAL and PARALLEL cannot be combined as they
 * represent incompatible execution patterns that would create undefined behavior in
 * processing chains.
 *
 * This validation is essential for maintaining system stability and ensuring that
 * processing tokens represent achievable execution configurations.
 */
inline void validate_token(ProcessingToken token)
{
    if ((token & SAMPLE_RATE) && (token & FRAME_RATE)) {
        throw std::invalid_argument("SAMPLE_RATE and FRAME_RATE are mutually exclusive.");
    }
 
    if ((token & CPU_PROCESS) && (token & GPU_PPOCESS)) {
        throw std::invalid_argument("CPU_PROCESS and GPU_PROCESS are mutually exclusive.");
    }
 
    if ((token & SEQUENTIAL) && (token & PARALLEL)) {
        throw std::invalid_argument("SEQUENTIAL and PARALLEL are mutually exclusive.");
    }
}
 
/**
 * @brief Determines if two processing tokens are compatible for joint execution
 * @param preferred The preferred processing token configuration
 * @param current The current processing token configuration being evaluated
 * @return true if the tokens are compatible, false otherwise
 *
 * This function implements sophisticated compatibility logic that goes beyond simple equality
 * checking to determine if processors with different token requirements can work together
 * in the same processing pipeline. The compatibility rules are designed to maximize
 * processing flexibility while maintaining system stability and performance.
 *
 * **Rate Compatibility Rules:**
 * - FRAME_RATE processors require FRAME_RATE execution contexts (strict requirement)
 * - SAMPLE_RATE processors can adapt to FRAME_RATE contexts (flexible upward compatibility)
 * - Same-rate combinations are always compatible
 *
 * **Device Compatibility Rules:**
 * - SAMPLE_RATE processing cannot execute on GPU hardware (hardware limitation)
 * - GPU-preferred processors cannot fall back to CPU execution (performance requirement)
 * - CPU-preferred processors can use GPU for FRAME_RATE processing only
 *
 * **Concurrency Compatibility Rules:**
 * - Sequential/Parallel differences are acceptable if rate requirements align
 * - Mismatched concurrency with incompatible rates is rejected
 * - Same concurrency patterns are always compatible
 *
 * This flexibility enables the system to optimize processing chains by allowing compatible
 * processors to share execution contexts while preventing configurations that would result
 * in poor performance or execution failures.
 */
inline bool are_tokens_compatible(ProcessingToken preferred, ProcessingToken current)
{
    bool preferred_sample = preferred & SAMPLE_RATE;
    bool preferred_frame = preferred & FRAME_RATE;
    bool current_sample = current & SAMPLE_RATE;
    bool current_frame = current & FRAME_RATE;
 
    // If preferred is FRAME_RATE, only FRAME_RATE is compatible
    if (preferred_frame && !current_frame)
        return false;
    // If preferred is SAMPLE_RATE, FRAME_RATE can be compatible (sample can "delay" to frame)
    if (preferred_sample && current_frame)
        return true;
    // If both are SAMPLE_RATE or both are FRAME_RATE, compatible
    if ((preferred_sample && current_sample) || (preferred_frame && current_frame))
        return true;
 
    // Device compatibility: SAMPLE_RATE can't run on GPU, but FRAME_RATE can run on CPU
    bool preferred_cpu = preferred & CPU_PROCESS;
    bool preferred_gpu = preferred & GPU_PPOCESS;
    bool current_cpu = current & CPU_PROCESS;
    bool current_gpu = current & GPU_PPOCESS;
 
    if (preferred_sample && current_gpu)
        return false; // Can't run sample rate on GPU
    if (preferred_gpu && current_cpu)
        return false; // If preferred is GPU, but current is CPU, not compatible
    // If preferred is CPU, but current is GPU, allow only for FRAME_RATE
    if (preferred_cpu && current_gpu && !current_frame)
        return false;
 
    // Sequential/Parallel compatibility: allow if rates align
    bool preferred_seq = preferred & SEQUENTIAL;
    bool preferred_par = preferred & PARALLEL;
    bool current_seq = current & SEQUENTIAL;
    bool current_par = current & PARALLEL;
 
    if ((preferred_seq && current_par) || (preferred_par && current_seq)) {
        // Allow if rates align (already checked above)
        if ((preferred_sample && current_sample) || (preferred_frame && current_frame))
            return true;
        // If preferred is SAMPLE_RATE and current is FRAME_RATE, already handled above
        // Otherwise, not compatible
        return false;
    }
 
    // If all checks pass, compatible
    return true;
}
 
/**
 * @brief Gets the optimal processing token for a given buffer type and system configuration
 * @param buffer_type Type identifier for the buffer (e.g., "audio", "video", "texture")
 * @param system_capabilities Available system capabilities (GPU, multi-core CPU, etc.)
 * @return Recommended processing token for optimal performance
 *
 * This function analyzes buffer characteristics and system capabilities to recommend
 * the most appropriate processing token configuration. It considers factors like:
 * - Buffer data type and size characteristics
 * - Available hardware acceleration
 * - System performance characteristics
 * - Current system load and resource availability
 *
 * The recommendations help achieve optimal performance by matching processing
 * requirements with available system capabilities.
 */
inline ProcessingToken get_optimal_token(const std::string& buffer_type, uint32_t system_capabilities)
{
    // Implementation would analyze buffer type and system capabilities
    // This is a placeholder for the actual optimization logic
    if (buffer_type == "audio") {
        return (system_capabilities & 0x1) ? AUDIO_PARALLEL : AUDIO_BACKEND;
    } else if (buffer_type == "video" || buffer_type == "texture") {
        return GRAPHICS_BACKEND;
    }
    return AUDIO_BACKEND; // Safe default
}
 
}
 
namespace std {
template <>
struct hash<std::pair<MayaFlux::Buffers::ProcessingToken, MayaFlux::Buffers::ProcessingToken>> {
    size_t operator()(const std::pair<MayaFlux::Buffers::ProcessingToken, MayaFlux::Buffers::ProcessingToken>& pair) const
    {
        return hash<uint32_t>()(static_cast<uint32_t>(pair.first)) ^ (hash<uint32_t>()(static_cast<uint32_t>(pair.second)) << 1);
    }
};
}