Monstra

KO | EN

gitlite — search

#react #ai #golang #machine-learning #linux #docker #java #awesome #cli #kubernetes #vue #pytorch #mcp #open-source

(★ 90)

High-performance Swift framework for task execution, memory caching, and data management with intelligent execution merging, TTL caching, and retry logic

File Explorer

Download Latest Version (.zip)

- - architecture.mdc
  - workflow.mdc
- - bug-report.md
  - bug_report.md
  - feature-request.md
  - feature_request.md
- - ci.yml
  - docs.yml
  - scheduled-tests-dev.yml
  - scheduled-tests.yml
- pull_request_template.md
- custom-head.html
- dark-mode.css
- generate-docs.sh
- - KVHeavyTasksManager.swift
  - KVLightTasksManager.swift
  - MonoTask.swift
- - CPUTimeStamp.swift
  - DoublyLink.swift
  - HashQueue.swift
  - Heap.swift
  - RetryCount.swift
  - TracingIDFactory.swift
- - KVHeavyTasksManagerTests.swift
  - KVLightTasksManagerTests.swift
  - MonoTaskClearResultTests.swift
  - MonoTaskCrossScenarioTests.swift
  - MonoTaskForceUpdateTests.swift
  - MonoTaskTests.swift
- - CPUTimeStampPerformanceTests.swift
  - CPUTimeStampTests.swift
  - DoublyLinkTests.swift
  - HashQueueTests.swift
  - HeapPerformanceTests.swift
  - HeapTests.swift
  - RetryCountTests.swift
  - TracingIDFactoryTest.swift
.gitignore
.jazzy.yaml
.swiftformat
.swiftlint.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
Logo-banner.png
Logo.png
Monstra.podspec
Package.swift
README.md
README_CN.md
SECURITY.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Swift](https://img.shields.io/badge/Swift-5.5-orange.svg)](https://swift.org)
[![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20macOS%20%7C%20tvOS%20%7C%20watchOS-lightgrey.svg)](https://developer.apple.com)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/yangchenlarkin/Monstra/main/LICENSE)
[![Swift Package Manager](https://img.shields.io/badge/Swift%20Package%20Manager-compatible-brightgreen.svg)](https://github.com/apple/swift-package-manager)
[![CocoaPods](https://img.shields.io/badge/CocoaPods-compatible-brightgreen.svg)](https://cocoapods.org)
[![Docs](https://img.shields.io/badge/docs-API%20Reference-blue)](https://yangchenlarkin.github.io/Monstra/)

**English** | [简体中文](README_CN.md)

A high-performance Swift framework providing efficient task execution, memory caching, and data management utilities with intelligent execution merging, TTL caching, and retry logic.

Documentation: <a href="https://yangchenlarkin.github.io/Monstra/" target="_blank" rel="noopener noreferrer">API Reference (Jazzy)</a>

## 🚀 Features

### Monstore - Caching System

#### MemoryCache
- **⏰ TTL & Priority Support**: Advanced time-to-live functionality with automatic expiration and configurable priority-based eviction
- **💥 Avalanche Protection**: Intelligent TTL randomization prevents cache stampede and simultaneous expiration cascades
- **🛡️ Breakdown Protection**: Comprehensive null value caching and robust key validation for enhanced reliability
- **📊 Statistics & Monitoring**: Built-in cache statistics, performance metrics, and real-time monitoring capabilities

### Monstask - Task Execution Framework

#### **MonoTask**

- **🔄 Execution Merging**: Multiple concurrent requests merged into single execution
- **⏱️ TTL Caching**: Results cached for configurable duration with automatic expiration
- **🔄 Advanced Retry Logic**: Exponential backoff, fixed intervals, and hybrid retry strategies
- **🎯 Manual Cache Control**: Fine-grained cache invalidation with execution strategy options

#### **KVLightTasksManager**
- **📈 Peak Shaving**: Prevents excessive task execution volume through Priority-Based Scheduling (LIFO/FIFO strategies with configurable limits)
- **🔄 Batch Processing**: Support for single and batch data provisioning to enhance backend execution efficiency
- **📊 Concurrent Execution**: Configurable concurrent task limits (default: 4 running, 256 queued)
- **🎯 Execution Merging**: Intelligent request deduplication and merging to prevent duplicate work and optimize resource usage
- **💾 Result Caching**: Integrated MemoryCache for optimized performance

#### **KVHeavyTasksManager**
- **📊 Progress Tracking**: Real-time progress updates with custom event publishing and broadcasting capabilities
- **🎯 Priority-Based Scheduling**: Advanced LIFO/FIFO strategies with intelligent interruption support
- **🔄 Task Lifecycle Management**: Complete start/stop/resume functionality with provider state preservation
- **📱 Concurrent Control**: Optimized concurrent execution limits (default: 2 running, 64 queued)
- **🎯 Execution Merging**: Intelligent request deduplication and merging to prevent duplicate work and optimize resource usage
- **💾 Result Caching**: Integrated MemoryCache for enhanced performance and efficiency

## 🚀 Quick Start

### Installation

#### Swift Package Manager (Recommended)

Add Monstra to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/yangchenlarkin/Monstra.git", from: "0.1.0")
]
```

Or add it directly in Xcode:
1. File → Add Package Dependencies
2. Enter the repository URL: `https://github.com/yangchenlarkin/Monstra.git`
3. Select the version you want to use

#### CocoaPods

Add Monstra to your `Podfile`:

```ruby
pod 'Monstra', '~> 0.1.0'
```

**Note**: Monstra is published as a unified framework, so you get all components together.

## 🎯 When to Use Each Component

| Component | Best For | Key Features |
|-----------|----------|-------------|
| **MonoTask** | Single expensive operations | Execution merging, TTL caching, retry logic |
| **KVLightTasksManager** | Fast, lightweight operations | Batch processing, key validation, high throughput |
| **KVHeavyTasksManager** | Resource-intensive operations | Progress tracking, lifecycle management, error recovery |

#### **Some Scenarios for Each Component**

- **MonoTask**: API calls, database queries, expensive computations that benefit from caching and deduplication
- **KVLightTasksManager**: User profile fetching, search results, configuration loading, high-frequency operations
- **KVHeavyTasksManager**: File downloads, video processing, ML inference, long-running operations with progress updates

## 💡 Simple Examples

### 1. MemoryCache
Basic caching operations with TTL, priority-based and LRU eviction.

**Simple Example (Default Configuration):**
```swift
import Monstra

// Create a basic cache with default configuration
let cache = MemoryCache<String, Int>()

// Set values with different priorities and TTL
cache.set(element: 42, for: "answer", priority: 10.0, expiredIn: 3600.0) // 1 hour, high priority
cache.set(element: 100, for: "score", priority: 1.0) // Default TTL, low priority
cache.set(element: nil, for: "user-999") // Cache null value

// Get values using the FetchResult enum
switch cache.getElement(for: "answer") {
case .hitNonNullElement(let value):
    print("Found answer: \(value)")
case .hitNullElement:
    print("Found null value")
case .miss:
    print("Key not found or expired")
case .invalidKey:
    print("Invalid key")
}

// Check cache status
print("Cache count: \(cache.count)")
print("Cache capacity: \(cache.capacity)")
print("Is empty: \(cache.isEmpty)")
print("Is full: \(cache.isFull)")

// Remove specific element
let removed = cache.removeElement(for: "score")
print("Removed: \(removed ?? -1)")

// Clean up expired elements
cache.removeExpiredElements()
```

**Detailed Configuration Example:**
```swift
// Advanced configuration with all options
let imageCache = MemoryCache<String, Data>(
    configuration: .init(
        // Thread Safety: Enable DispatchSemaphore synchronization for concurrent access
        enableThreadSynchronization: true,
        
        // Memory & Capacity Limits: Maximum 100 items, 50MB memory usage
        memoryUsageLimitation: .init(
            capacity: 100,    // Maximum number of cached items
            memory: 50        // Maximum memory usage in MB
        ),
        
        // TTL Settings: How long items stay in cache
        defaultTTL: 1800.0,              // 30 minutes for regular elements
        defaultTTLForNullElement: 300.0, // 5 minutes for null/nil elements
        
        // Cache Stampede Prevention: Randomize TTL by ±30 seconds
        ttlRandomizationRange: 30.0,     // Prevents all items expiring simultaneously
        
        // Key Validation: Only accept keys starting with "img_"
        keyValidator: { key in
            return key.hasPrefix("img_")  // Custom validation logic
        },
        
        // Memory Cost Calculation: Use actual data size for eviction decisions
        costProvider: { data in
            return data.count             // Return size in bytes
        }
    )
)
```

### 2. MonoTask  
**Single Task Execution & Merging**: Handles individual task execution, request merging and result cache, such as module initialization, configuration file reading, and API call consolidation with result caching (e.g., UserProfile, e-commerce Cart operations)

**Simple Example (Default Configuration):**
```swift
import Monstra

// Create a basic task with minimal configuration
let networkTask = MonoTask<Data> { callback in
    // Your network request logic here
    let url = URL(string: "https://api.example.com/data")!
    URLSession.shared.dataTask(with: url) { data, response, error in
        if let error = error {
            callback(.failure(error))
        } else if let data = data {
            callback(.success(data))
        }
    }.resume()
}

// Alternatively, you can use an asynchornic block to create MonoTask

// Multiple execution patterns - only one network request
// Note: All executions benefit from MonoTask's execution merging

// Execute with async/await
let result1: Result<Data, Error> = await networkTask.asyncExecute()
switch result1 {
case .success(let data):
    print("Got data: \(data.count) bytes")
case .failure(let error):
    print("Error: \(error)")
}

// Execute with async/await and try/catch
do {
    let result2: Data = try await networkTask.executeThrows() // Second execution, returns cached result
    print("Result2: \(result2)")
} catch {
    print("Result2 error: \(error)")
}

// Fire-and-forget execution
networkTask.justExecute()

// Callback-based execution
networkTask.execute { result in
    switch result {
    case .success(let data):
        print("Result3 (callback): \(data.count) bytes")
    case .failure(let error):
        print("Result3 (callback) error: \(error)")
    }
}
```

**Detailed Configuration Example:**
```swift
// Advanced configuration with custom retry and queue settings
let fileProcessor1 = MonoTask<ProcessedData>(
    retry: 3,  // Simple retry count configuration
    
    // Result Caching: Use default cache configuration
    resultExpireDuration: 300.0,      // 5 minutes cache duration
    
    // Task Queue: Custom dispatch queue for task execution
    taskQueue: DispatchQueue.global(qos: .utility),  // Background priority queue
    
    // Callback Queue: Custom dispatch queue for callbacks
    callbackQueue: DispatchQueue.global(qos: .userInitiated)  // High priority queue
) { callback in
    // Your file processing logic here
    let filePath = "/path/to/large/file.txt"
    do {
        let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
        let processedData = ProcessedData(content: data, metadata: ["size": data.count])
        callback(.success(processedData))
    } catch {
        callback(.failure(error))
    }
}
// Advanced configuration with custom retry and queue settings
let fileProcessor2 = MonoTask<ProcessedData>(
    // Retry Strategy: Exponential backoff with 3 attempts
    retry: .count(
        count: 3,    // Maximum retry attempts
        intervalProxy: .exponentialBackoff(
            initialTimeInterval: 1.0,  // Start with 1 second delay
            scaleRate: 2.0             // Double the delay each retry
        )
    ),
    
    // Result Caching: Use default cache configuration
    resultExpireDuration: 300.0,      // 5 minutes cache duration
    
    // Task Queue: Custom dispatch queue for task execution
    taskQueue: DispatchQueue.global(qos: .utility),  // Background priority queue
    
    // Callback Queue: Custom dispatch queue for callbacks
    callbackQueue: DispatchQueue.global(qos: .userInitiated)  // High priority queue
) { callback in
    // Your file processing logic here
    let filePath = "/path/to/large/file.txt"
    do {
        let data = try Data(contentsOf: URL(fileURLWithPath: filePath))
        let processedData = ProcessedData(content: data, metadata: ["size": data.count])
        callback(.success(processedData))
    } catch {
        callback(.failure(error))
    }
}
```

**Async Task Block Example:**
```swift
// Async/await initialization with modern Swift concurrency
let unzipTask = MonoTask<[String]>(
    // Retry Strategy: Fixed interval retry for file operations
    retry: .count(
        count: 2,    // Retry twice for file system issues
        intervalProxy: .fixed(timeInterval: 1.0)  // Wait 1 second between retries
    ),
    
    // Result Caching: Cache unzipped file list for 10 minutes
    resultExpireDuration: 600.0,      // 10 minutes cache duration
    
    // Task Queue: Background queue for file operations
    taskQueue: DispatchQueue.global(qos: .utility),
    
    // Callback Queue: Main queue for UI updates
    callbackQueue: DispatchQueue.main
) {
    // Async task block that returns Result directly
    do {
        let archivePath = "/path/to/archive.zip"
        let extractPath = "/path/to/extract/"
        
        // Simulate async unzip operation
        let extractedFiles = try await unzipArchive(at: archivePath, to: extractPath)
        return .success(extractedFiles)
    } catch {
        return .failure(error)
    }
}

// Usage with async/await
let extractedFiles = try await unzipTask.executeThrows()
print("Extracted \(extractedFiles.count) files")
```

### 3. KVLightTasksManager
**High-Volume Task Execution**: Handles high-volume operations with peak shaving, such as image downloads, local database batch reads, map tile downloads and cache warming operations

**Simple Example (Default Configuration):**
```swift
import Monstra

// Create a lightweight tasks manager for handling image downloads
let imageTaskManager = KVLightTasksManager<UIImage> { (imageURL: URL, completion: @escaping (Result<UIImage?, Error>) -> Void) in
    // Simple image download task
    URLSession.shared.dataTask(with: imageURL) { data, response, error in
        if let error = error {
            completion(.failure(error))
        } else if let data = data, let image = UIImage(data: data) {
            completion(.success(image))
        } else {
            completion(.failure(NSError(domain: "ImageError", code: -1, userInfo: nil)))
        }
    }.resume()
}

// Fetch multiple images
let imageURLs = [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg", 
    "https://example.com/image3.jpg"
].compactMap { URL(string: $0) }

// Fetch images individually
for (index, url) in imageURLs.enumerated() {
    imageTaskManager.fetch(key: url) { key, result in
        switch result {
        case .success(let image):
            if let image = image {
                print("Image \(index + 1) downloaded successfully: \(image.size)")
            } else {
                print("Image \(index + 1) returned nil")
            }
        case .failure(let error):
            print("Image \(index + 1) failed: \(error)")
        }
    }
}

// Fetch multiple images at once with batch callback
imageTaskManager.fetch(keys: imageURLs) { key, result in
    switch result {
    case .success(let image):
        if let image = image {
            print("Image downloaded: \(image.size)")
        } else {
            print("Image returned nil")
        }
    case .failure(let error):
        print("Image failed: \(error)")
    }
}
```

**Batch Processing Example:**
```swift
// Create a manager for batch fetching user profile data
let userProfileManager = KVLightTasksManager<[String: UserProfile?]> { (userIDs: [String], completion: @escaping (Result<[String: UserProfile?], Error>) -> Void) in
    // Simulate batch API call to fetch multiple user profiles
    DispatchQueue.global(qos: .utility).async {
        // Simulate network delay
        Thread.sleep(forTimeInterval: 0.1)
        
        var profiles: [String: UserProfile?] = [:]
        
        // Simulate batch API response
        for userID in userIDs {
            let profile = UserProfile(
                id: userID,
                name: "User \(userID)",
                email: "user\(userID)@example.com",
                avatar: "https://example.com/avatars/\(userID).jpg"
            )
            profiles[userID] = profile
        }
        
        completion(.success(profiles))
    }
}

// Fetch multiple user profiles in a single batch
let userIDs = ["user1", "user2", "user3"]

// Using batch callback for all results at once
userProfileManager.fetch(keys: userIDs, multiCallback: { results in
    print("Batch loaded \(results.count) users:")
    for (userID, result) in results {
        switch result {
        case .success(let profile):
            if let profile = profile {
                print("  ✓ \(profile.name) (\(profile.email))")
            } else {
                print("  - \(userID): No profile found")
            }
        case .failure(let error):
            print("  ✗ \(userID): \(error)")
        }
    }
})

// Using individual callbacks for each user (still benefits from batch processing)
userProfileManager.fetch(keys: userIDs) { userID, result in
    switch result {
    case .success(let profile):
        if let profile = profile {
            print("Individual: \(profile.name) loaded")
        } else {
            print("Individual: \(userID) - No profile found")
        }
    case .failure(let error):
        print("Individual: \(userID) - \(error)")
    }
}
```

**Advanced Configuration Example:**
```swift
// Create a manager with custom configuration for image downloads
let imageManager = KVLightTasksManager<UIImage>(
    config: .init(
        dataProvider: .multiprovide(maximumBatchCount: 4) { (imageURLs: [String], completion: @escaping (Result<[String: UIImage?], Error>) -> Void) in
            // Download multiple images in parallel
            let group = DispatchGroup()
            var results = [String: UIImage?]()
            let lock = NSLock()
            
            for urlString in imageURLs {
                group.enter()
                
                guard let url = URL(string: urlString) else {
                    lock.lock()
                    results[urlString] = nil
                    lock.unlock()
                    group.leave()
                    continue
                }
                
                URLSession.shared.dataTask(with: url) { data, response, error in
                    defer { group.leave() }
                    
                    lock.lock()
                    if let data = data, let image = UIImage(data: data) {
                        results[urlString] = image
                    } else {
                        results[urlString] = nil
                    }
                    lock.unlock()
                }.resume()
            }
            
            group.notify(queue: .main) {
                completion(.success(results))
            }
        },
        maxNumberOfQueueingTasks: 32,     // Queue up to 32 image requests
        maxNumberOfRunningTasks: 4,       // Download 4 images simultaneously
        retryCount: 1,                    // Retry failed downloads once
        PriorityStrategy: .FIFO,          // Process oldest requests first
        cacheConfig: .init(
            capacity: 100,                // Cache up to 100 images
            memory: 50,                   // 50MB memory limit
            defaultTTL: 3600.0,           // 1 hour cache duration
            enableThreadSynchronization: true
        )
    )
)

// Download multiple images
let imageURLs = [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg",
    "https://example.com/image3.jpg"
]

// Download all images
imageManager.fetch(keys: imageURLs) { url, result in
    switch result {
    case .success(let image):
        if let image = image {
            print("✓ Downloaded: \(image.size)")
        } else {
            print("- Failed to download: \(url)")
        }
    case .failure(let error):
        print("✗ Error: \(error)")
        }
    }
```

### 4. KVHeavyTasksManager

**Resource-Intensive Operations**: Handles demanding tasks such as large file downloads, video processing, and ML inference with comprehensive progress tracking

#### SimpleDataProvider implementation

Notes:
- `SimpleDataProvider` is intentionally minimal (blocking I/O, no progress/resume) for clarity.
- For production downloads with progress/resume/cancellation, see the advanced providers in
  `Examples/KVHeavyTasksManager/LargeFileDownloadManagement`.

```swift
import Foundation
import Monstra

enum SimpleDataProviderEvent {
    case didStart
    case didFinish
}

/// Minimal synchronous provider for educational purposes only.
class SimpleDataProvider: Monstra.KVHeavyTaskBaseDataProvider<URL, Data, SimpleDataProviderEvent>, Monstra.KVHeavyTaskDataProviderInterface {
    let semaphore = DispatchSemaphore(value: 1)
    var isRunning = false {
        didSet { customEventPublisher(isRunning ? .didStart : .didFinish) }
    }

func start() {
        semaphore.wait(); defer { semaphore.signal() }
        guard !isRunning else { return }
        isRunning = true

DispatchQueue.global().async {
            let result: Result<Data?, Error>
            do {
                let data = try Data(contentsOf: self.key, options: .mappedIfSafe)
                result = .success(data)
            } catch {
                result = .failure(error)
            }

self.semaphore.wait(); defer { self.semaphore.signal() }
            guard self.isRunning else { return }
            self.isRunning = false
            self.resultPublisher(result)
        }
    }

@discardableResult
    func stop() -> KVHeavyTaskDataProviderStopAction {
        semaphore.wait(); defer { semaphore.signal() }
        guard isRunning else { return .dealloc }
        isRunning = false
        return .dealloc
    }
}
```

#### Minimal usage

```swift
import Monstra

// Educational provider that does a blocking read on a background queue
// See: Examples/KVHeavyTasksManager/LargeFileDownloadManagement/Sources/.../SimpleDataProvider.swift
typealias SimpleHeavyManager = KVHeavyTasksManager<URL, Data, SimpleDataProviderEvent, SimpleDataProvider>

let manager = SimpleHeavyManager(config: .init())
let fileURL = URL(string: "https://example.com/file.bin")!

// Observe simple start/finish events and get the result
manager.fetch(
    key: fileURL,
    customEventObserver: { event in
        switch event {
        case .didStart:  print("SimpleDataProvider: didStart")
        case .didFinish: print("SimpleDataProvider: didFinish")
        }
    },
    result: { result in
        switch result {
        case .success(let data):
            print("Downloaded: \(data.count) bytes")
        case .failure(let error):
            print("Failed: \(error)")
        }
    }
)
```

## 🚀 Advanced Examples

### **⚡ MonoTask - Task Execution Scenarios**
<table width="100%">
  <colgroup>
    <col width="40%" />
    <col width="40%" />
    <col width="20%" />
  </colgroup>
  <thead>
    <tr>
      <th>Scenarios</th>
      <th>Best Practices</th>
      <th>Example Link</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Module Initialization</td>
      <td>Cache app configuration with retry logic</td>
      <td><a href="Examples/MonoTask/ModuleInitialization">Module Initialization</a></td>
    </tr>
    <tr>
      <td>UserProfile Manager</td>
      <td>Single-instance user profile management with caching</td>
      <td><a href="Examples/MonoTask/UserProfileManager">UserProfile Manager</a></td>
    </tr>
  </tbody>
 </table>

### **🚀 KVLightTasksManager - Light Task Scenarios**
<table width="100%">
  <colgroup>
    <col width="40%" />
    <col width="40%" />
    <col width="20%" />
  </colgroup>
  <thead>
    <tr>
      <th>Scenarios</th>
      <th>Best Practices</th>
      <th>Example Link</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Object Fetch Task</td>
      <td>Batch fetch objects by ID list with performance enhancement</td>
      <td><a href="Examples/KVLightTasksManager/ObjectFetchTask">Object Fetch Task</a></td>
    </tr>
  </tbody>
 </table>

### **🏗️ KVHeavyTasksManager - Heavy Task Scenarios**
<table width="100%">
  <colgroup>
    <col width="40%" />
    <col width="40%" />
    <col width="20%" />
  </colgroup>
  <thead>
    <tr>
      <th>Scenarios</th>
      <th>Best Practices</th>
      <th>Example Link</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Large File Download Management</td>
      <td>Large file downloads with progress tracking</td>
      <td><a href="Examples/KVHeavyTasksManager/LargeFileDownloadManagement">Large File Downloader</a></td>
    </tr>
    <tr>
      <td>Large File Unzip</td>
      <td>Processing large archive files with progress tracking and resource management</td>
      <td><a href="Examples/KVHeavyTasksManager/LargeFileUnzip">Large File Unzip</a></td>
    </tr>
  </tbody>
 </table>

## 📋 Requirements

### Platform Support
- **iOS**: 13.0+
- **macOS**: 10.15+
- **tvOS**: 13.0+
- **watchOS**: 6.0+

### Swift Version
- **Swift**: 5.5+

### Dependencies
- **Foundation**: Built-in (no external dependencies)
- **Alamofire**: Only for example executable (not required for core library)

## 🛡️ Key Advantages & Protection Mechanisms

### **Monstore Protection Features**

### **Cache Stampede Prevention**
Monstra prevents cache stampede attacks through TTL randomization. When multiple cache entries expire simultaneously, it can cause a sudden surge of requests to your backend. Monstra randomizes expiration times within a configurable range to distribute the load.

```swift
let cache = MemoryCache<String, Data>(
    configuration: .init(
        ttlRandomizationRange: 30.0 // ±30 seconds randomization
    )
)
```

### **Avalanche Protection**
Monstra protects against memory avalanches by implementing intelligent eviction policies. When memory usage approaches limits, the system automatically evicts the least valuable entries based on priority, recency, and expiration status.

```swift
let cache = MemoryCache<String, UIImage>(
    configuration: .init(
        memoryUsageLimitation: .init(
            capacity: 1000,    // Max 1000 images
            memory: 500        // Max 500MB
        )
    )
)
```

### **Breakdown Protection**
Monstra prevents cache breakdowns through priority-based LRU eviction. Critical data with higher priority is retained longer, while less important data is evicted first when capacity is reached.

```swift
// Set high priority for critical data
cache.set(element: userProfile, for: "user-123", priority: 10.0)

// Set low priority for temporary data
cache.set(element: searchResults, for: "search-query", priority: 1.0)
```

### **Null Element Caching**
Monstra supports caching null/nil elements with separate TTL configuration, preventing repeated database queries for non-existent data.

```swift
let cache = MemoryCache<String, User?>(
    configuration: .init(
        defaultTTL: 3600.0,           // Regular data: 1 hour
        defaultTTLForNullElement: 300.0  // Null data: 5 minutes
    )
)

// Cache both existing and non-existing users
cache.set(element: user, for: "user-123")      // Regular cache
cache.set(element: nil, for: "user-999")      // Null cache
```

### **Monstask Protection Features**

#### **MonoTask - Execution Merging & Deduplication**
MonoTask prevents duplicate work through intelligent execution merging. When multiple concurrent requests are made for the same task, only one execution occurs while all callbacks receive the same result.

```swift
let task = MonoTask<String>(resultExpireDuration: 60.0) { callback in
    // Expensive network call
    performExpensiveOperation(callback)
}

// Multiple concurrent calls - only one network request
Task {
    let result1 = await task.asyncExecute() // Network call happens
    let result2 = await task.asyncExecute() // Returns cached result
    let result3 = await task.asyncExecute() // Returns cached result
}
```

#### **MonoTask - Advanced Retry Strategies**
MonoTask provides sophisticated retry mechanisms with exponential backoff, fixed intervals, and hybrid approaches to handle transient failures gracefully.

```swift
// Exponential backoff with 3 retries
let retryTask = MonoTask<Data>(
    retry: .count(
        count: 3, 
        intervalProxy: .exponentialBackoff(
            initialTimeInterval: 1.0, 
            scaleRate: 2.0
        )
    ),
    resultExpireDuration: 300.0
) { callback in
    performNetworkRequest(callback)
}

// Fixed interval retry
let fixedRetryTask = MonoTask<Data>(
    retry: .count(
        count: 5, 
        intervalProxy: .fixed(timeInterval: 2.0)
    )
) { callback in
    performDatabaseQuery(callback)
}
```

#### **MonoTask - Execution State Management**
MonoTask provides fine-grained control over task execution states with cancellation, restart, and completion strategies.

```swift
// Cancel ongoing execution immediately
task.clearResult(ongoingExecutionStrategy: .cancel)

// Let execution complete, then restart
task.clearResult(ongoingExecutionStrategy: .restart)

// Let execution complete normally, just clear cache
task.clearResult(ongoingExecutionStrategy: .allowCompletion)
```

#### **MonoTask - Multiple Execution Patterns**
MonoTask supports various execution patterns to fit different use cases and coding styles.

```swift
// Async/await (recommended for modern Swift)
let result = await task.asyncExecute()
switch result {
case .success(let data):
    updateUI(with: data)
case .failure(let error):
    showErrorMessage(error)
}

// Callback-based (for legacy code integration)
task.execute { result in
    switch result {
    case .success(let data):
        updateUI(with: data)
    case .failure(let error):
        showErrorMessage(error)
    }
}

// Fire-and-forget (for pre-warming cache)
task.justExecute()
// Later, this will likely return cached result
let result = await task.asyncExecute()
```

#### **Task Managers - Priority-Based Scheduling**
KVLightTasksManager and KVHeavyTasksManager provide priority-based scheduling with LIFO/FIFO strategies for optimal resource utilization.

```swift
let lightManager = KVLightTasksManager<String, User>(
    config: .init(
        dataProvider: .asyncMonoprovide { key in
            try await API.fetchUser(id: key)
        },
        PriorityStrategy: .LIFO,  // Latest requests get priority
        maxNumberOfRunningTasks: 4,
        maxNumberOfQueueingTasks: 256
    )
)

let heavyManager = KVHeavyTasksManager<String, Video>(
    config: .init(
        dataProvider: .asyncMonoprovide { key in
            try await VideoProcessor.process(key)
        },
        PriorityStrategy: .FIFO,  // Fair processing order
        maxNumberOfRunningTasks: 2,  // Limited for heavy operations
        maxNumberOfQueueingTasks: 64
    )
)
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Workflow

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`swift test`)
6. Run linting (`swiftlint lint Sources/`)
7. Commit your changes (`git commit -m 'Add amazing feature'`)
8. Push to the branch (`git push origin feature/amazing-feature`)
9. Submit a pull request

### Code Style
- Follow Swift API Design Guidelines
- Use meaningful variable and function names
- Add comprehensive documentation comments
- Ensure all public APIs have unit tests
- Maintain performance benchmarks

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by high-performance cache implementations
- Built with Swift's excellent type system and performance characteristics
- Tested extensively for production readiness
- Special thanks to the Swift community for feedback and contributions
- Special thanks to [Cursor](https://cursor.sh) - AI-first code editor for enhancing development productivity

---

**Made with ❤️ for the Swift community**

Monstra

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Monstra

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README