HACache

public class HACache<ValueType>

Cache

This class functions as a shared container of queries which can be live-updated from subscriptions. For example, you might combine HARequestType.getStates with HAEventType.stateChanged to get all states and be alerted for changes.

All methods on this class are thread-safe.

Important

You, or another object, must keep a strong reference to this cache or a HACancellable returned to you; the cache does not retain itself directly. This includes map values.

Note

Use shouldResetWithoutSubscribers to control whether the subscription is disconnected when not in use.

Note

Use map(_:) to make quasi-streamed changes to the cache contents.

  • Create a cache

    This method is provided as a convenience to avoid having to wrap single-subscribe versions in an array.

    Declaration

    Swift

    public convenience init(
    connection: HAConnection,
    populate: HACachePopulateInfo<ValueType>,
    subscribe: HACacheSubscribeInfo<ValueType>...
)

    Parameters

    connection

    The connection to use and watch
    populate

    The info on how to fetch the initial/update data
    subscribe

    The info (one or more) for what subscriptions to start for updates or triggers for populating

  • Create a cache

    Declaration

    Swift

    public init(
    connection: HAConnection,
    populate: HACachePopulateInfo<ValueType>,
    subscribe: [HACacheSubscribeInfo<ValueType>]
)

    Parameters

    connection

    The connection to use and watch
    populate

    The info on how to fetch the initial/update data
    subscribe

    The info (one or more) for what subscriptions to start for updates or triggers for populating

  • Create a cache that relies on subscription updates without initial population.

    Declaration

    Swift

    public init(
    connection: HAConnection,
    subscribe: HACacheSubscribeInfo<ValueType?>
)

    Parameters

    connection

    The connection to use and watch
    subscribe

    The info (one or more) for what subscriptions to start for updates or triggers for populating

  • Create a cache by mapping an existing cache’s value

    Declaration

    Swift

    public init<IncomingType>(
    from incomingCache: HACache<IncomingType>,
    transform: @escaping (IncomingType) -> ValueType
)

    Parameters

    incomingCache

    The cache to map values from; this is kept as a strong reference
    transform

    The transform to apply to the values from the cache

  • Create a cache with a constant value

    This is largely intended for tests or other situations where you want a cache you can control more strongly.

    Declaration

    Swift

    public init(constantValue: ValueType)

    Parameters

    constantValue

    The value to keep for state

  • The current value, if available, or the most recent value from a previous connection. A value would not be available when the initial request hasn’t been responded to yet.

    Declaration

    Swift

    public var value: ValueType? { get }

  • Whether the cache will unsubscribe from its subscription and reset its current value without any subscribers

    Note

    This is unrelated to whether the cache instance is kept in memory itself.

    Declaration

    Swift

    public var shouldResetWithoutSubscribers: Bool { get set }

  • Subscribe to changes of this cache

    No guarantees are made about the order added subscriptions will be invoked in.

    Declaration

    Swift

    public func subscribe(_ handler: @escaping (HACancellable, ValueType) -> Void) -> HACancellable

    Parameters

    handler

    The handler to invoke when changes occur

    Return Value

    A token to cancel the subscription; either this token or the HACache instance must be retained.

  • Receive either the current value, or the next available value, from the cache

    Declaration

    Swift

    @discardableResult
public func once(_ handler: @escaping (ValueType) -> Void) -> HACancellable

    Parameters

    handler

    The handler to invoke

    Return Value

    A token to cancel the once lookup

  • Map the value to a new cache

    Important

    You, or another object, must strongly retain this newly-created cache or a cancellable for it.

    Declaration

    Swift

    public func map<NewType>(_ transform: @escaping (ValueType) -> NewType) -> HACache<NewType>

    Parameters

    transform

    The transform to apply to this cache’s value

    Return Value

    The new cache

  • If this cache was created with populate info, this contains that info This is largely intended for tests and is not used internally.

    Declaration

    Swift

    public let populateInfo: HACachePopulateInfo<ValueType>?

  • If this cache was created with subscribe info, this contains that info This is largely intended for tests and is not used internally.

    Declaration

    Swift

    public let subscribeInfo: [HACacheSubscribeInfo<ValueType>]?

  • If this cache was created with subscribe info, this contains that info This is largely intended for tests and is not used internally.

    Declaration

    Swift

    public let subscribeOnlyInfo: HACacheSubscribeInfo<ValueType?>?