KVHeavyTasksManager

public class KVHeavyTasksManager<
    K,
    Element,
    CustomEvent,
    DataProvider: KVHeavyTaskBaseDataProvider<K, Element, CustomEvent>
> where DataProvider: KVHeavyTaskDataProviderInterface

extension KVHeavyTasksManager: @unchecked Sendable

Comprehensive manager for resource-intensive computational tasks and operations.

KVHeavyTasksManager serves as the central coordination hub for executing, caching, and managing heavy computational tasks. It provides sophisticated concurrency control, intelligent caching, flexible priority strategies, and comprehensive lifecycle management for resource-intensive operations.

Architecture Overview

The manager operates through several interconnected systems:

• Task Queue Management: Dual-queue system (waiting/running) with configurable capacity and eviction
• Priority Coordination: FIFO/LIFO strategies with optional task interruption support
• Cache Integration: Multi-level caching with hit/miss/null/invalid state handling
• Provider Lifecycle: DataProvider creation, reuse, and cleanup with memory optimization
• Event Broadcasting: Real-time progress updates and custom event distribution
• Thread Safety: Complete concurrency protection using semaphore-based synchronization

Key Features

• Zero-configuration operation: Sensible defaults for immediate use
• Highly configurable: Every aspect of behavior can be customized
• Memory efficient: Automatic cleanup and configurable resource limits
• Performance optimized: Minimal overhead with intelligent caching and provider reuse
• Robust error handling: Comprehensive error propagation and graceful degradation
• Production ready: Thread-safe, tested, and optimized for high-load scenarios

Generic Type Parameters

• K: Key type for task identification (must be Hashable) - used for deduplication and caching
• Element: Result type returned by completed tasks - cached and delivered to callbacks
• CustomEvent: Event type for progress updates - broadcast to all registered observers
• DataProvider: Concrete provider class that executes the actual heavy operations

Usage Example

// Define your custom data provider
class ImageProcessingProvider: KVHeavyTaskBaseDataProvider<String, UIImage, ProcessingProgress>,
                              KVHeavyTaskDataProviderInterface {
    func start() {
        // Implement heavy image processing
        performImageProcessing { progress in
            customEventPublisher(progress)
        } completion: { result in
            resultPublisher(result)
        }
    }

    func stop() -> KVHeavyTaskDataProviderStopAction {
        return .reuse // Preserve processing state for resumption
    }
}

// Configure and create manager
let config = KVHeavyTasksManager<String, UIImage, ProcessingProgress, ImageProcessingProvider>.Config(
    maxNumberOfRunningTasks: 2,
    priorityStrategy: .LIFO(.stop),
    cacheConfig: .init(memoryUsageLimitation: .init(capacity: 100, memory: 50_000_000))
)
let manager = KVHeavyTasksManager<String, UIImage, ProcessingProgress, ImageProcessingProvider>(config: config)

// Execute tasks with progress monitoring
manager.fetch(key: "process_photo_123",
              customEventObserver: { progress in
                  print("Processing progress: \(progress.percentage)%")
              },
              result: { result in
                  switch result {
                  case .success(let image):
                      // Handle processed image
                  case .failure(let error):
                      // Handle processing error
                  }
              })

Thread Safety

All public methods are fully thread-safe and can be called from any queue or thread. The manager uses internal synchronization to coordinate access to shared state while minimizing performance impact through careful lock scope management.

Performance Considerations

• Queue sizing: Balance memory usage vs task eviction risk
• Concurrency limits: Optimize for your specific task characteristics and system resources
• Cache configuration: Tune for your result size and access patterns
• Priority strategy: Choose based on responsiveness vs predictability requirements
• Provider lifecycle: Balance setup cost vs memory usage with reuse/dealloc decisions