MemoryCacheDriver class

An in-memory cache driver implementation for the Khadem framework.

This driver provides fast, volatile caching using a Dart Map as the underlying storage. It's ideal for caching frequently accessed data that doesn't need to persist across application restarts. The driver includes automatic TTL (time-to-live) expiration, statistics tracking, and efficient memory management.

Key Features

  • High Performance: Fast O(1) operations using HashMap
  • TTL Support: Automatic expiration of cache entries
  • Statistics Tracking: Built-in performance metrics
  • Memory Efficient: Minimal memory overhead
  • Thread Safe: Safe for concurrent access within a single isolate
  • Automatic Cleanup: Background task removes expired entries

Usage

// Create a memory cache driver
final cache = MemoryCacheDriver();

// Store data with TTL
await cache.put('user:123', {'name': 'John', 'email': 'john@example.com'}, Duration(hours: 1));

// Retrieve data
final user = await cache.get('user:123');

// Check if key exists
final exists = await cache.has('user:123');

// Remove specific key
await cache.forget('user:123');

// Clear all cache
await cache.clear();

// Get cache statistics
final stats = cache.getStats();
print('Hit rate: ${stats.hitRate}%');

Performance Characteristics

  • put(): O(1) - Constant time insertion
  • get(): O(1) - Constant time retrieval
  • has(): O(1) - Constant time existence check
  • forget(): O(1) - Constant time deletion
  • clear(): O(n) - Linear time for all entries

Memory Management

The driver uses Dart's built-in garbage collection for memory management. Cache entries are automatically cleaned up when they expire or are explicitly removed. No manual memory management is required.

Thread Safety

This implementation is thread-safe within a single Dart isolate. However, since Dart isolates do not share memory, each isolate would have its own cache instance. For cross-isolate caching, consider using the file-based cache driver with external synchronization.

Limitations

  • Volatility: Data is lost when the application restarts
  • Memory Bound: Limited by available RAM
  • No Persistence: Cannot survive application crashes
  • Isolate Scoped: Not shared between Dart isolates
Implemented types

Constructors

MemoryCacheDriver()
Creates a new MemoryCacheDriver instance.

Properties

hashCode → int
The hash code for this object.
no setterinherited
itemCount → int
Gets the current number of items in the cache.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

add(String key, dynamic value, Duration ttl) → Future<bool>
Stores a value in the cache if the key does not exist.
override
clear() → Future<void>
Clears all items from the cache.
override
decrement(String key, [int amount = 1]) → Future<int>
Decrement the value of an item in the cache.
override
dispose() → void
Disposes of the cache driver and cleans up resources.
forget(String key) → Future<void>
Removes a value from the cache by its key.
override
get(String key) → Future
Retrieves a value from the cache by its key.
override
getStats() → CacheStats
Gets cache statistics.
has(String key) → Future<bool>
Checks if a key exists in the cache and has not expired.
override
increment(String key, [int amount = 1]) → Future<int>
Increment the value of an item in the cache.
override
many(List<String> keys) → Future<Map<String, dynamic>>
Retrieves multiple values from the cache by their keys.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pull(String key) → Future
Retrieve an item from the cache and delete it.
override
put(String key, dynamic value, Duration ttl) → Future<void>
Stores a value in the cache with a specified time-to-live (TTL).
override
putMany(Map<String, dynamic> values, Duration ttl) → Future<void>
Stores multiple values in the cache.
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited