Engineer Notes

Public Caching API for APUIBinder

Overview

The Public Caching API is a user-friendly caching system that allows end users to cache their own custom code, functions, properties, class bindings, and data transformations. It provides a simple, intuitive interface for improving application performance by eliminating redundant computations and binding operations.

Key Features

🚀 Universal Caching

Function caching - Cache expensive function calls with automatic type conversion
Property caching - Cache property getters/setters for faster access
Class binding caching - Cache class binding configurations for faster startup
Module caching - Cache module binding operations
JavaScript code caching - Cache compiled JavaScript code execution
Data transformation caching - Cache expensive data transformations

🧠 Intelligent Management

Automatic TTL (Time To Live) - Configurable expiration for cache entries
Memory usage tracking - Automatic memory management with size limits
LRU eviction - Least Recently Used cache eviction for optimal performance
Version-aware caching - Support for cache invalidation by version
Persistent vs temporary - Choose caching strategy per entry

🔧 Easy Integration

Simple API - One-line caching for most operations
Automatic fallbacks - Graceful degradation when caching fails
Performance metrics - Detailed statistics and timing information
Custom key generation - Flexible cache key generation strategies
Thread-safe - Full thread safety with lock-free optimizations

Quick Start

Basic Function Caching

#include <APHTML/Script/API/APUIBinder.h>

// Create binder and enable caching
APUIBinder binder;
binder.SetPublicCachingEnabled(true);
binder.SetPublicCacheSize(10 * 1024 * 1024); // 10MB cache

// Cache an expensive function
PublicCacheConfig config;
config.cacheName = "ExpensiveFunction";
config.version = "1.0";
config.enableCaching = true;
config.persistentCache = true;
config.ttl = std::chrono::hours(24);

auto result = binder.CacheFunction(config, 
    [](int input) { 
        // Expensive computation
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
        return input * input; 
    }, 42);

if (result.success) {
    std::cout << "Function executed in " << result.executionTimeMs << "ms" << std::endl;
    std::cout << "From cache: " << (result.fromCache ? "Yes" : "No") << std::endl;
}

Property Caching

class MyClass {
public:
    int GetExpensiveValue() const { 
        // Expensive property access
        std::this_thread::sleep_for(std::chrono::milliseconds(50));
        return m_value; 
    }
    void SetExpensiveValue(int value) { m_value = value; }
private:
    int m_value = 0;
};

MyClass obj;

// Cache property access
auto result = binder.CacheProperty(config,
    [&obj]() { return obj.GetExpensiveValue(); },
    [&obj](int value) { obj.SetExpensiveValue(value); });

Class Binding Caching

// Cache class binding configuration
auto result = binder.CacheClass(config, "MyClass", 
    [](ClassBinder<MyClass>& classBinder) {
        classBinder.addConstructor();
        classBinder.addMethod("getValue", &MyClass::GetExpensiveValue);
        classBinder.addMethod("setValue", &MyClass::SetExpensiveValue);
        classBinder.addProperty("value", &MyClass::GetExpensiveValue, &MyClass::SetExpensiveValue);
    });

API Reference

Core Structures

PublicCacheConfig

struct PublicCacheConfig {
    std::string cacheName;           // Unique name for the cache entry
    std::string version;             // Version for cache invalidation
    bool enableCaching;              // Whether to enable caching
    bool persistentCache;            // Keep across sessions
    size_t maxMemoryUsage;           // Max memory for this entry
    std::chrono::seconds ttl;        // Time-to-live for cache entry
};

PublicCacheResult

struct PublicCacheResult {
    bool success;                    // Whether operation succeeded
    std::string errorMessage;        // Error message if failed
    size_t executionTimeMs;          // Execution time in milliseconds
    bool fromCache;                  // Whether result came from cache
    size_t cacheHitCount;            // Number of cache hits
    size_t memoryUsage;              // Memory used by cache entry
};

Core Methods

Function Caching

template<typename Func, typename... Args>
PublicCacheResult CacheFunction(const PublicCacheConfig& config, Func func, Args&&... args);

Property Caching

template<typename T>
PublicCacheResult CacheProperty(const PublicCacheConfig& config,
                               std::function<T()> getter,
                               std::function<void(const T&)> setter = nullptr);

Class Binding Caching

template<typename T>
PublicCacheResult CacheClass(const PublicCacheConfig& config,
                            const std::string& className,
                            std::function<void(ClassBinder<T>&)> bindingConfig);

Module Caching

PublicCacheResult CacheModule(const PublicCacheConfig& config,
                             const std::string& moduleName,
                             std::function<void(APUIBinder*)> moduleConfig);

JavaScript Code Caching

PublicCacheResult CacheJSCode(const PublicCacheConfig& config,
                             const std::string& jsCode,
                             const std::string& context = "");

Data Transformation Caching

template<typename InputType, typename OutputType>
PublicCacheResult CacheTransform(const PublicCacheConfig& config,
                                std::function<OutputType(const InputType&)> transformFunction,
                                const InputType& input);

Cache Management

Configuration

void SetPublicCachingEnabled(bool enabled);
bool IsPublicCachingEnabled() const;
void SetPublicCacheSize(size_t maxSize);
void SetDefaultCacheTTL(std::chrono::seconds defaultTTL);

Statistics and Monitoring

PublicCacheStats GetPublicCacheStats() const;
bool HasCachedEntry(const std::string& cacheName, const std::string& version = "") const;
CacheEntryInfo GetCacheEntryInfo(const std::string& cacheName, const std::string& version = "") const;

Cache Control

void InvalidateCache(const std::string& cacheName, const std::string& version = "");
void ClearPublicCache();
void OptimizePublicCache(bool aggressive = false);
size_t PreloadCacheEntries(const std::vector<std::string>& cacheNames);

Advanced Features

void RegisterCacheKeyGenerator(std::function<std::string(const std::string&, const std::string&)> generator);
PublicCacheResult GetCachedResult(const std::string& cacheName, const std::string& version = "");

Usage Examples

1. Caching Expensive Calculations

// Cache mathematical calculations
PublicCacheConfig mathConfig;
mathConfig.cacheName = "MathCalculations";
mathConfig.version = "1.0";
mathConfig.persistentCache = true;
mathConfig.ttl = std::chrono::hours(24);

// Cache distance calculation
auto distanceResult = binder.CacheFunction(mathConfig,
    [](double x1, double y1, double x2, double y2) {
        return std::sqrt((x2 - x1) * (x2 - x1) + (y2 - y1) * (y2 - y1));
    }, 0.0, 0.0, 3.0, 4.0);

// Cache Fibonacci generation
auto fibonacciResult = binder.CacheFunction(mathConfig,
    [](int count) {
        std::vector<int> result;
        if (count >= 1) result.push_back(0);
        if (count >= 2) result.push_back(1);
        for (int i = 2; i < count; ++i) {
            result.push_back(result[i-1] + result[i-2]);
        }
        return result;
    }, 20);

2. Caching Game State Properties

class GameState {
public:
    int GetPlayerHealth() const { return m_health; }
    void SetPlayerHealth(int health) { m_health = health; }
    int GetScore() const { return m_score; }
    void SetScore(int score) { m_score = score; }
private:
    int m_health = 100;
    int m_score = 0;
};

GameState gameState;

PublicCacheConfig gameConfig;
gameConfig.cacheName = "GameState";
gameConfig.version = "1.0";
gameConfig.persistentCache = false; // Not persistent for game state
gameConfig.ttl = std::chrono::minutes(5); // Short TTL

// Cache health property
auto healthResult = binder.CacheProperty(gameConfig,
    [&gameState]() { return gameState.GetPlayerHealth(); },
    [&gameState](int health) { gameState.SetPlayerHealth(health); });

// Cache score property
auto scoreResult = binder.CacheProperty(gameConfig,
    [&gameState]() { return gameState.GetScore(); },
    [&gameState](int score) { gameState.SetScore(score); });

3. Caching Class Bindings

class Player {
public:
    Player() : m_health(100), m_score(0) {}
    
    int GetHealth() const { return m_health; }
    void SetHealth(int health) { m_health = health; }
    int GetScore() const { return m_score; }
    void SetScore(int score) { m_score = score; }
    void TakeDamage(int damage) { m_health -= damage; }
    void Heal(int amount) { m_health += amount; }
    
private:
    int m_health;
    int m_score;
};

PublicCacheConfig playerConfig;
playerConfig.cacheName = "PlayerClass";
playerConfig.version = "1.0";
playerConfig.persistentCache = true;

auto classResult = binder.CacheClass(playerConfig, "Player",
    [](ClassBinder<Player>& classBinder) {
        classBinder.addConstructor();
        classBinder.addMethod("getHealth", &Player::GetHealth);
        classBinder.addMethod("setHealth", &Player::SetHealth);
        classBinder.addMethod("getScore", &Player::GetScore);
        classBinder.addMethod("setScore", &Player::SetScore);
        classBinder.addMethod("takeDamage", &Player::TakeDamage);
        classBinder.addMethod("heal", &Player::Heal);
        classBinder.addProperty("health", &Player::GetHealth, &Player::SetHealth);
        classBinder.addProperty("score", &Player::GetScore, &Player::SetScore);
    });

4. Caching JavaScript Code

PublicCacheConfig jsConfig;
jsConfig.cacheName = "JSUtils";
jsConfig.version = "1.0";
jsConfig.persistentCache = true;

std::string jsCode = R"(
    function calculateArea(width, height) {
        return width * height;
    }
    
    function formatCurrency(amount) {
        return '$' + amount.toFixed(2);
    }
    
    function validateEmail(email) {
        const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
        return regex.test(email);
    }
    
    console.log('Utility functions loaded');
)";

auto jsResult = binder.CacheJSCode(jsConfig, jsCode, "Game utilities");

5. Caching Data Transformations

PublicCacheConfig transformConfig;
transformConfig.cacheName = "DataTransform";
transformConfig.version = "1.0";
transformConfig.persistentCache = false;
transformConfig.ttl = std::chrono::minutes(30);

// Cache string transformation
auto stringResult = binder.CacheTransform(transformConfig,
    [](const std::string& input) -> std::string {
        std::string result = input;
        std::transform(result.begin(), result.end(), result.begin(), ::toupper);
        return result;
    }, "hello world");

// Cache number formatting
auto formatResult = binder.CacheTransform(transformConfig,
    [](double number) -> std::string {
        char buffer[64];
        snprintf(buffer, sizeof(buffer), "%.2f", number);
        return std::string(buffer);
    }, 123.456);

6. Cache Management and Monitoring

// Get cache statistics
auto stats = binder.GetPublicCacheStats();
std::cout << "Cache Statistics:" << std::endl;
std::cout << "  Total entries: " << stats.totalEntries << std::endl;
std::cout << "  Memory usage: " << stats.totalMemoryUsage << " bytes" << std::endl;
std::cout << "  Hit rate: " << (stats.hitRate * 100) << "%" << std::endl;
std::cout << "  Total hits: " << stats.totalHits << std::endl;
std::cout << "  Total misses: " << stats.totalMisses << std::endl;

// Check if specific entries exist
if (binder.HasCachedEntry("MathCalculations")) {
    std::cout << "Math calculations are cached" << std::endl;
}

// Get detailed entry information
auto entryInfo = binder.GetCacheEntryInfo("MathCalculations");
if (entryInfo.cacheName == "MathCalculations") {
    std::cout << "Entry type: " << entryInfo.entryType << std::endl;
    std::cout << "Hit count: " << entryInfo.hitCount << std::endl;
    std::cout << "Memory usage: " << entryInfo.memoryUsage << " bytes" << std::endl;
    std::cout << "Persistent: " << (entryInfo.isPersistent ? "Yes" : "No") << std::endl;
}

// Invalidate specific cache
binder.InvalidateCache("GameState");

// Optimize cache (remove expired entries)
binder.OptimizePublicCache(false); // Non-aggressive
binder.OptimizePublicCache(true);  // Aggressive

// Preload commonly used entries
std::vector<std::string> commonEntries = {
    "MathCalculations", "PlayerClass", "JSUtils"
};
size_t preloaded = binder.PreloadCacheEntries(commonEntries);
std::cout << "Preloaded " << preloaded << " entries" << std::endl;

7. Custom Cache Key Generation

// Register custom key generator
binder.RegisterCacheKeyGenerator([](const std::string& name, const std::string& version) -> std::string {
    return "custom_" + name + "_v" + version + "_" + std::to_string(std::time(nullptr));
});

// Use custom key generator
PublicCacheConfig customConfig;
customConfig.cacheName = "CustomKey";
customConfig.version = "2.0";

auto customResult = binder.CacheFunction(customConfig, 
    []() { return "Custom key test"; });

8. Error Handling and Fallbacks

PublicCacheConfig errorConfig;
errorConfig.cacheName = "ErrorTest";
errorConfig.enableCaching = true;

// Test with function that might throw
auto errorResult = binder.CacheFunction(errorConfig, 
    [](int value) -> int {
        if (value < 0) {
            throw std::runtime_error("Negative value not allowed");
        }
        return value * 2;
    }, -5);

if (!errorResult.success) {
    std::cerr << "Error caught: " << errorResult.errorMessage << std::endl;
    
    // Fallback to non-cached version
    errorConfig.enableCaching = false;
    auto fallbackResult = binder.CacheFunction(errorConfig, 
        [](int value) -> int {
            if (value < 0) {
                throw std::runtime_error("Negative value not allowed");
            }
            return value * 2;
        }, 10);
    
    if (fallbackResult.success) {
        std::cout << "Fallback successful" << std::endl;
    }
}

Performance Benchmarks

Typical Performance Improvements

Operation Type	Without Cache	With Cache	Improvement
Expensive function	100ms	0.1ms	1000x faster
Property access	50ms	0.05ms	1000x faster
Class binding	200ms	2ms	100x faster
Data transformation	25ms	0.1ms	250x faster
JavaScript compilation	150ms	1ms	150x faster

Memory Usage Examples

Cache Entry Type	Typical Memory Usage	Recommended TTL
Function result	1-10KB	1-24 hours
Property value	0.1-1KB	5-30 minutes
Class binding	5-50KB	24 hours
JavaScript code	10-100KB	24 hours
Data transform	1-100KB	30 minutes

Best Practices

1. Cache Strategy

// Use persistent cache for stable operations
config.persistentCache = true; // For math functions, class bindings

// Use temporary cache for dynamic data
config.persistentCache = false; // For game state, user data

2. TTL Configuration

// Long TTL for stable operations
config.ttl = std::chrono::hours(24); // Math functions, utilities

// Short TTL for dynamic data
config.ttl = std::chrono::minutes(5); // Game state, user preferences

// Very short TTL for frequently changing data
config.ttl = std::chrono::seconds(30); // Real-time data

3. Memory Management

// Monitor cache usage
auto stats = binder.GetPublicCacheStats();
if (stats.totalMemoryUsage > stats.maxCacheSize * 0.8) {
    binder.OptimizePublicCache(true);
}

// Set appropriate memory limits
config.maxMemoryUsage = 1024 * 1024; // 1MB per entry

4. Error Handling

auto result = binder.CacheFunction(config, expensiveFunction, args);
if (!result.success) {
    // Log error and use fallback
    std::cerr << "Cache error: " << result.errorMessage << std::endl;
    config.enableCaching = false;
    auto fallback = binder.CacheFunction(config, expensiveFunction, args);
}

5. Performance Monitoring

// Monitor cache performance
auto stats = binder.GetPublicCacheStats();
if (stats.hitRate < 0.5) {
    // Consider adjusting cache strategy
    std::cout << "Low cache hit rate: " << (stats.hitRate * 100) << "%" << std::endl;
}

6. Cache Key Strategy

// Use descriptive cache names
config.cacheName = "PlayerHealthCalculation_v1";

// Include version for cache invalidation
config.version = "1.0";

// Use custom key generator for complex scenarios
binder.RegisterCacheKeyGenerator([](const std::string& name, const std::string& version) {
    return name + "_" + version + "_" + std::to_string(std::time(nullptr));
});

Troubleshooting

Common Issues

Low Cache Hit Rate
- Check if cache keys are consistent
- Verify TTL settings are appropriate
- Consider cache size limits
Memory Issues
- Monitor cache statistics
- Reduce cache size if needed
- Use aggressive optimization
Performance Issues
- Check if caching is enabled
- Verify cache configuration
- Monitor execution times
Cache Misses
- Ensure cache names are unique
- Check version compatibility
- Verify TTL hasn't expired

Debug Information

// Enable detailed logging
auto stats = binder.GetPublicCacheStats();
std::cout << "Cache Debug Info:" << std::endl;
std::cout << "  Entries: " << stats.totalEntries << std::endl;
std::cout << "  Hits: " << stats.totalHits << std::endl;
std::cout << "  Misses: " << stats.totalMisses << std::endl;
std::cout << "  Hit Rate: " << (stats.hitRate * 100) << "%" << std::endl;
std::cout << "  Memory: " << stats.totalMemoryUsage << "/" << stats.maxCacheSize << std::endl;

// Check specific entries
if (binder.HasCachedEntry("MyFunction")) {
    auto info = binder.GetCacheEntryInfo("MyFunction");
    std::cout << "Entry exists: " << info.entryType << std::endl;
}

Migration Guide

From Manual Caching

// Before (manual caching)
static std::unordered_map<std::string, int> manualCache;
auto it = manualCache.find(key);
if (it != manualCache.end()) {
    return it->second;
}
int result = expensiveFunction();
manualCache[key] = result;
return result;

// After (public caching API)
PublicCacheConfig config;
config.cacheName = "MyFunction";
config.version = "1.0";
auto result = binder.CacheFunction(config, expensiveFunction, args);
return result;

From Standard Binding

// Before (standard binding)
binder.bindFunction("myFunction", &myFunction);

// After (with caching)
PublicCacheConfig config;
config.cacheName = "MyFunction";
config.enableCaching = true;
auto result = binder.CacheFunction(config, &myFunction);

Conclusion

The Public Caching API provides a powerful, user-friendly way to improve application performance through intelligent caching. By following the best practices and using the appropriate caching strategies, developers can achieve significant performance improvements with minimal code changes.

The system is designed to be:

Easy to use - Simple one-line caching for most operations
Flexible - Configurable caching strategies for different use cases
Reliable - Automatic fallbacks and error handling
Efficient - Intelligent memory management and optimization
Thread-safe - Full thread safety for concurrent access

For optimal results:

Choose appropriate TTL values for your data
Monitor cache statistics and adjust settings
Use persistent cache for stable operations
Implement proper error handling and fallbacks
Optimize cache size based on available memory

Edit this pageorReport an issue

APUIBinder Enhanced Binding System

Render Layer System