{"id":32149446,"url":"https://github.com/sleepwalkerfx/quantumcache","last_synced_at":"2025-10-21T09:57:51.390Z","repository":{"id":255597308,"uuid":"851846545","full_name":"sleepwalkerfx/QuantumCache","owner":"sleepwalkerfx","description":"QuantumCache is a high-performance thread safe Least Recently Used (LRU) cache implementation in Swift that supports complex data types.","archived":false,"fork":false,"pushed_at":"2024-09-04T10:48:52.000Z","size":29,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-21T09:57:42.525Z","etag":null,"topics":["cache","generic","high-performance","high-performance-computing","in-memory-caching","in-memory-storage","ios","lru-cache","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sleepwalkerfx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-03T19:48:35.000Z","updated_at":"2025-03-27T23:11:12.000Z","dependencies_parsed_at":"2024-09-06T07:55:36.786Z","dependency_job_id":"1386542d-8978-495e-8968-bd9197173387","html_url":"https://github.com/sleepwalkerfx/QuantumCache","commit_stats":null,"previous_names":["sleepwalkerfx/quantumcache"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/sleepwalkerfx/QuantumCache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepwalkerfx%2FQuantumCache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepwalkerfx%2FQuantumCache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepwalkerfx%2FQuantumCache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepwalkerfx%2FQuantumCache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sleepwalkerfx","download_url":"https://codeload.github.com/sleepwalkerfx/QuantumCache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sleepwalkerfx%2FQuantumCache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280240316,"owners_count":26296527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","generic","high-performance","high-performance-computing","in-memory-caching","in-memory-storage","ios","lru-cache","swift"],"created_at":"2025-10-21T09:57:50.646Z","updated_at":"2025-10-21T09:57:51.382Z","avatar_url":"https://github.com/sleepwalkerfx.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QuantumCache\n\n**QuantumCache** is a thread-safe, high-performance Least Recently Used (LRU) cache implementation in Swift. It is designed to be fast and efficient, supporting various types of cached content, including complex types and enums with generic associated values.\n\n## Features\n\n- **Generic Cache Implementation**: Works with any type conforming to `CachableContent`.\n- **High Performance**: Optimized for speed with an efficient LRU eviction strategy.\n- **Support for Complex Types**: Handles custom classes and enums with associated values and generic types.\n\n## Time Complexity\n\n- **O(1) Access and Update**: QuantumCache provides constant-time complexity for both retrieving (getting) and inserting (putting) items in the cache. This is achieved through a combination of a hash map for fast lookups and a doubly linked list to maintain the order of usage.\n- **O(1) Eviction**: When the cache exceeds its capacity, the least recently used (LRU) item is evicted in constant time, ensuring that the performance remains consistent even as the cache fills up.\n\n## Advantages Over NSCache\n\nWhile `NSCache` is a powerful and convenient caching solution in Swift, `QuantumCache` offers several advantages:\n\n- **Support for Value Types**: Unlike `NSCache`, which primarily works with reference types, `QuantumCache` can efficiently cache value types (e.g., structs, enums) in addition to reference types. This makes it more versatile and suitable for a broader range of use cases.\n\n- **No NSObject Subclass Required**: Unlike `NSCache`, which requires cached objects to be subclasses of `NSObject`, `QuantumCache` does not impose such a restriction. This allows you to use plain Swift structs, enums, and classes. Using plain Swift types can be more efficient and align better with Swift’s value semantics, avoiding the overhead associated with `NSObject` subclassing.\n\n- **Deterministic Eviction Policy**: `QuantumCache` follows a strict Least Recently Used (LRU) eviction policy. This deterministic approach ensures that the oldest unused item is always removed first when the cache exceeds its capacity. `NSCache`, on the other hand, may not strictly adhere to LRU, as its eviction policy is based on internal heuristics and system memory pressure.\n  \n- **Thread Safety**: `QuantumCache` uses `NSRecursiveLock` to ensure thread-safe operations across multiple threads. While `NSCache` is also thread-safe, `QuantumCache`'s locking mechanism is transparent and designed to handle more complex access patterns, such as nested locking scenarios.\n\n- **Fine-Grained Control**: `QuantumCache` provides more granular control over the cache's behavior, allowing developers to customize the eviction process and tailor the cache for specific needs. This level of control is not directly available with `NSCache`.\n\n- **Predictable Performance**: With constant-time complexity for both insertion and access operations, `QuantumCache` offers predictable and consistent performance, which is critical for applications where cache performance is a bottleneck.\n\n- **Customization**: The `CachableContent` protocol allows developers to define custom cacheable types with any associated data. This level of customization isn't as straightforward with `NSCache`.\n\n\n\n## Installation\n\nYou can add `QuantumCache` to your Swift project by using Swift Package Manager. Add the following dependency to your `Package.swift`:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/sleepwalkerfx/QuantumCache.git\", from: \"1.0.0\")\n]\n```\n\n## Usage\n\nHere’s a basic example of how to use `QuantumCache`:\n\n```swift\nimport QuantumCache\n\nstruct MyContent: CachableContent {\n    var id: Int\n    var content: String\n}\n\nlet cache = QuantumCache\u003cMyContent\u003e(capacity: 3)\nlet item1 = MyContent(id: 1, content: \"Hello\")\nlet item2 = MyContent(id: 2, content: \"World\")\n\ncache.put(item1)\ncache.put(item2)\n\nif let retrievedItem = cache.get(1) {\n    print(retrievedItem.content) // Output: Hello\n}\n```\n## Advanced Usage\n\n**QuantumCache** has been thoroughly tested with various complex types to ensure robustness and correctness.\n\n### 1. Custom Classes with Reference Semantics\n\n**QuantumCache** has been tested to ensure it correctly handles custom classes where instances are referenced rather than copied. This includes:\n\n- **Reference Equality**: Confirming that the cache maintains references to the same instances.\n- **Mutability**: Verifying that changes to cached objects are reflected when retrieved.\n- **Eviction**: Ensuring proper eviction behavior with reference-type objects.\n\n#### Example:\n\nHere’s how you can define and use a `QuantumCache` with custom classes:\n\n```swift\n// Define a custom class conforming to `CachableContent`\nclass ReferenceContent: CachableContent {\n    var id: Int\n    var content: String\n    \n    init(id: Int, content: String) {\n        self.id = id\n        self.content = content\n    }\n}\n\n// Create a QuantumCache instance with a specified capacity\nlet cache = QuantumCache\u003cReferenceContent\u003e(capacity: 3)\n\n// Create instances of ReferenceContent\nlet firstItem = ReferenceContent(id: 1, content: \"First Item\")\nlet secondItem = ReferenceContent(id: 2, content: \"Second Item\")\nlet thirdItem = ReferenceContent(id: 3, content: \"Third Item\")\n\n// Put items into the cache\ncache.put(firstItem)\ncache.put(secondItem)\ncache.put(thirdItem)\n\n// Access items from the cache and modify them\nif let cachedFirstItem = cache.get(1) {\n    print(\"Retrieved cached first item: \\(cachedFirstItem.content)\")\n    // Modify the content of the retrieved item\n    cachedFirstItem.content = \"Updated First Item\"\n}\n\n// Insert more items to trigger eviction\nlet fourthItem = ReferenceContent(id: 4, content: \"Fourth Item\")\ncache.put(fourthItem)\n\n// Access previously cached items\nif let updatedFirstItem = cache.get(1) {\n    print(\"Retrieved updated first item: \\(updatedFirstItem.content)\")\n}\n\nif let cachedSecondItem = cache.get(2) {\n    print(\"Retrieved cached second item: \\(cachedSecondItem.content)\")\n} else {\n    print(\"Second item has been evicted\")\n}\n\nif let cachedThirdItem = cache.get(3) {\n    print(\"Retrieved cached third item: \\(cachedThirdItem.content)\")\n} else {\n    print(\"Third item has been evicted\")\n}\n\nif let cachedFourthItem = cache.get(4) {\n    print(\"Retrieved cached fourth item: \\(cachedFourthItem.content)\")\n}\n```\n\n### 2. Enums with Associated Values\n\n**QuantumCache** supports enums with associated values and has been tested for:\n\n- **Equality and Hashing**: Ensuring that enums with associated values are correctly compared and hashed.\n- **Eviction**: Properly managing cache entries for enums with associated values.\n\n#### Example:\n\nHere's how you can define and use a `QuantumCache` with an enum that has associated values:\n\n```swift\n// Define the enum with associated values conforming to `CachableContent` and `Hashable`\nenum MockEnumContent: CachableContent, Hashable {\n    case text(id: Int, content: String)\n    case data(id: Int, content: Data)\n\n    // CachableContent Protocol Requirements\n    var id: Int {\n        switch self {\n        case .text(let id, _):\n            return id\n        case .data(let id, _):\n            return id\n        }\n    }\n\n    var content: Any {\n        switch self {\n        case .text(_, let content):\n            return content\n        case .data(_, let content):\n            return content\n        }\n    }\n}\n\n// Create a QuantumCache instance with a specified capacity\nlet cache = QuantumCache\u003cMockEnumContent\u003e(capacity: 5)\n\n// Put items into the cache\nlet textItem = MockEnumContent.text(id: 1, content: \"Hello, World!\")\ncache.put(textItem)\n\nlet dataItem = MockEnumContent.data(id: 2, content: Data([0x00, 0x01, 0x02]))\ncache.put(dataItem)\n\n// Access items from the cache\nif let cachedTextItem = cache.get(1) {\n    print(\"Retrieved cached text: \\(cachedTextItem)\")\n}\n\nif let cachedDataItem = cache.get(2) {\n    print(\"Retrieved cached data: \\(cachedDataItem)\")\n}\n\n// Example output:\n// Retrieved cached text: text(id: 1, content: \"Hello, World!\")\n// Retrieved cached data: data(id: 2, content: 3 bytes)\n```\n\n### 3. Enums with Generic Associated Types\n\n**QuantumCache** supports enums with generic associated values. It has been tested for:\n\n- **Equality**: Ensuring correct comparison of enums with generic types.\n- **Hashing**: Properly handling hashing for enums with generic values.\n- **Eviction**: Correctly evicting entries when the cache exceeds its capacity.\n\n#### Example:\n\nHere's how you can define and use a `QuantumCache` with an enum that has generic associated values:\n\n```swift\n// Define the enum with generic associated values conforming to `CachableContent`\nenum GenericEnumContent\u003cT\u003e: CachableContent {\n    case integer(id: Int, value: Int)\n    case string(id: Int, value: String)\n    case generic(id: Int, value: T)\n\n    // CachableContent Protocol Requirements\n    var id: Int {\n        switch self {\n        case .integer(let id, _):\n            return id\n        case .string(let id, _):\n            return id\n        case .generic(let id, _):\n            return id\n        }\n    }\n\n    var content: Any {\n        switch self {\n        case .integer(_, let value):\n            return value\n        case .string(_, let value):\n            return value\n        case .generic(_, let value):\n            return value\n        }\n    }\n}\n\n// Create a QuantumCache instance with a custom type for the associated type of .generic case\nlet cache = QuantumCache\u003cGenericEnumContent\u003cData\u003e\u003e(capacity: 5)\n\n// Put items into the cache\nlet intItem: GenericEnumContent\u003cData\u003e = GenericEnumContent.integer(id: 1, value: 42)\ncache.put(intItem)\n\nlet stringItem: GenericEnumContent\u003cData\u003e = GenericEnumContent.string(id: 2, value: \"Hello, Swift!\")\ncache.put(stringItem)\n\nlet genericItem = GenericEnumContent.generic(id: 3, value: Data([0x00, 0x01]))\ncache.put(genericItem)\n\n// Access items from the cache\nif let cachedIntItem = cache.get(1) {\n    print(\"Retrieved cached integer: \\(cachedIntItem)\")\n}\n\nif let cachedStringItem = cache.get(2) {\n    print(\"Retrieved cached string: \\(cachedStringItem)\")\n}\n\nif let cachedGenericItem = cache.get(3) {\n    print(\"Retrieved cached generic value: \\(cachedGenericItem)\")\n}\n\n// Example output:\n// Retrieved cached integer: integer(id: 1, value: 42)\n// Retrieved cached string: string(id: 2, value: \"Hello, Swift!\")\n// Retrieved cached generic value: generic(id: 3, value: 2 bytes)\n```\n\n## Running Tests\n\nTo run the tests, use the following command:\n```sh\nswift test\n```\n## Contributing\n\nContributions are welcome! Please open an issue or a pull request if you have suggestions, improvements, or bug fixes.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\nFor more detailed information on the implementation and usage, check out the code and tests in the repository.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleepwalkerfx%2Fquantumcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsleepwalkerfx%2Fquantumcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleepwalkerfx%2Fquantumcache/lists"}