Structures

A high-performance, in-memory key-value cache with configurable thread safety and memory management.

Core Features

• TTL (Time-to-Live) Expiration: Automatic cleanup of expired entries
• Priority-Based Eviction: Higher priority entries are retained longer during eviction
• LRU (Least Recently Used) Eviction: Within priority levels, least recently used entries are evicted first
• Null Element Caching: Support for caching null/nil elements with separate TTL configuration
• External Key Validation: Customizable key validation function set at initialization
• TTL Randomization: Prevents cache stampede by randomizing expiration times
• Configurable Thread Safety: Optional DispatchSemaphore synchronization for concurrent access
• Memory Usage Tracking: Configurable memory limits with automatic eviction

Thread Safety

• Synchronized Mode (enableThreadSynchronization=true): All operations are thread-safe using DispatchSemaphore
• Non-Synchronized Mode (enableThreadSynchronization=false): No synchronization; caller must ensure thread safety

Performance Characteristics

• Time Complexity: O(1) average case for get/set operations
• Memory Efficiency: Configurable capacity and memory limits
• Automatic Expiration: Background cleanup of expired entries
• Eviction Policy: Priority-based LRU eviction with memory limit enforcement

Example Usage

// Thread-synchronized cache with custom validation and memory limits
let imageCache = MemoryCache<String, UIImage>(
    configuration: .init(
        enableThreadSynchronization: true,
        memoryUsageLimitation: .init(capacity: 1000, memory: 500), // 500MB limit
        defaultTTL: 3600, // 1 hour
        keyValidator: { $0.hasPrefix("https://") },
        costProvider: { image in
            guard let cgImage = image.cgImage else { return 0 }
            return cgImage.bytesPerRow * cgImage.height // Returns bytes
        }
    )
)

// Non-synchronized cache for single-threaded scenarios
let fastCache = MemoryCache<String, Int>(
    configuration: .init(
        enableThreadSynchronization: false,
        memoryUsageLimitation: .init(capacity: 500, memory: 100)
    )
)

See more

public struct MemoryUsageLimitation

Statistics tracker for cache performance monitoring.

Tracks counts of cache results and computes derived metrics such as total accesses and hit rates. A lightweight report callback can be attached to observe each record.

• Thread-safety: This type is not synchronized; coordinate access externally if needed.

See more

public struct CacheStatistics

CPUTimeStamp: High-precision, monotonic CPU time for measurements and TTL logic.

• Monotonic source based on mach_absolute_time converted via cached mach_timebase_info
• Nanosecond-level precision with safe conversion order to avoid overflow

• Arithmetic and comparison operators for intervals and ordering

• Notes:

  • Intended for measuring intervals and scheduling expirations; not wall-clock time
  • Thread-safe and value-semantic; creation is fast
  • infinity and zero helpers simplify sentinel usage

See more

public struct CPUTimeStamp

extension CPUTimeStamp: Hashable

extension CPUTimeStamp: Equatable

extension CPUTimeStamp: Comparable

A high-performance unique ID generator optimized for distributed tracing and request tracking.

TracingIDFactory generates unique, monotonically increasing IDs that combine temporal and sequential components for excellent uniqueness guarantees across distributed systems. The factory uses a hybrid approach combining time-based base IDs with sequential counters to ensure both uniqueness and ordering.

Core Design Principles

Hybrid ID Generation

The factory generates IDs using the formula: ID = (timeBasedID × loopCount) + sequentialCounter

• Time-based component: Seconds since start of current year (UTC) - provides temporal ordering
• Sequential component: Incrementing counter that wraps at configurable loop count - ensures uniqueness
• Combined result: Globally unique ID with built-in temporal and sequential properties

Performance Characteristics

• High throughput: Generates millions of IDs per second with minimal overhead
• Memory efficient: Minimal state (3 Int64 values + lock)
• CPU optimized: Simple arithmetic operations, no string formatting or complex calculations
• Lock-free option: Unsafe variants avoid synchronization for maximum performance

Uniqueness Guarantees

• Temporal uniqueness: IDs generated at different times are naturally ordered
• Sequential uniqueness: IDs generated in rapid succession are guaranteed unique
• Cross-instance safety: Different instances initialized at different times generate different ID ranges
• Rollover handling: Sequential counter wraps safely without ID collisions

Usage Examples

// Basic usage with default settings (thread-safe)
var factory = TracingIDFactory()
let id1 = factory.safeNextString()     // "1234567890123456789"
let id2 = factory.safeNextUInt64()     // 1234567890123456790

// High-performance usage (requires external synchronization)
var factory = TracingIDFactory()
let fastID = factory.unsafeNextInt64() // Maximum performance

// Custom configuration for high-frequency scenarios
var highFreq = TracingIDFactory(loopCount: 1_000_000)
let customID = highFreq.safeNextUInt64()

Thread Safety

• Safe methods: Use internal os_unfair_lock for thread safety with minimal overhead
• Unsafe methods: No synchronization - caller must ensure thread safety or single-threaded access
• Mixed usage: Safe and unsafe methods can be mixed - each call is independent

Performance Considerations

• Safe vs Unsafe: Unsafe methods are ~10-15% faster, safe methods have negligible lock overhead
• Return type impact: All return types have similar performance (conversion is minimal)
• Initialization cost: One-time UTC calendar calculation - amortized across millions of IDs
• Memory footprint: ~64 bytes total including lock and temporal calculation state

See more

public struct TracingIDFactory