TTLPriorityLRUQueue

public class TTLPriorityLRUQueue<Key, Element> where Key : Hashable

TTLPriorityLRUQueue: Hybrid TTL + Priority + LRU cache.

This structure stores items with a time-to-live (TTL), an eviction priority, and tracks recency for LRU ordering. Eviction proceeds in the following order: 1) Expired entries 2) Lowest priority 3) Least-recently-used within the same priority

Complexity

O(1) average for set/get/remove by key; O(k) to purge k expired entries.
  • Thread-safety: Not thread-safe by itself; use external synchronization if needed.

  • The maximum number of elements the cache can hold.

    Declaration

    Swift

    public let capacity: Int

  • Returns true if the cache is empty.

    Declaration

    Swift

    public var isEmpty: Bool { get }

  • Returns true if the cache is full.

    Declaration

    Swift

    public var isFull: Bool { get }

  • The current number of elements in the cache.

    Declaration

    Swift

    public var count: Int { get }

  • Initializes a new empty cache with the specified capacity.

    Declaration

    Swift

    public init(capacity: Int)

    Parameters

    capacity

    Maximum elements allowed; negative values are treated as zero.

  • Inserts or updates an element for the given key, with optional priority and TTL.

    • Behavior:

      • Overwrites existing keys and refreshes both TTL and LRU position
      • Chooses insertion path based on whether the earliest TTL has already expired

    Declaration

    Swift

    @discardableResult
func set(
    element: Element,
    for key: Key,
    priority: Double = .zero,
    expiredIn duration: TimeInterval = .infinity
) -> Element?

    Parameters

    element

    The element to store
    key

    The key to associate with the element
    priority

    Eviction priority (higher values retained longer)
    duration

    TTL in seconds (default: .infinity)

    Return Value

    The evicted element, if any

  • Retrieves the element for the given key if present and not expired.

    Declaration

    Swift

    @discardableResult
func getElement(for key: Key) -> Element?

    Parameters

    key

    The key to look up

    Return Value

    The element if present and valid; otherwise nil (expired or missing)

  • Removes the element for the given key, if present.

    Declaration

    Swift

    @discardableResult
func removeElement(for key: Key) -> Element?

    Parameters

    key

    The key to remove

    Return Value

    The removed element, or nil if not found

  • Removes and returns one element following expiration/priority/LRU rules.

    Declaration

    Swift

    @discardableResult
func removeElement() -> Element?

    Return Value

    The removed element, or nil if the cache is empty

  • Removes all expired elements from the cache.

    Iteratively checks the TTL heap root (earliest expiration) and removes expired entries until the root is not expired. This ensures efficient cleanup without scanning all keys.

    Note

    O(k) where k is the number of expired entries removed.

    Declaration

    Swift

    func removeExpiredElements()