ContextualCache¶

interface ContextualCache<Identifier, Context, Failure, Value>

Stores information temporarily to avoid unneeded network requests.

Unlike Cache, a contextual cache stores multiple values per identifier. The context decides which value is visible. Here are a few examples of context usage:

authentication information (different users see different values)
paging information (different values are returned depending on the requested page)

The main advantage of using this interface rather than using a compound key in Cache is that it is possible to expire a value for all contexts.

In all other regards (cache states, cache chaining…), this interface is identical to Cache. Cache can be seen as a specialization of this interface for the case where the context is Unit.

Type Parameters¶

Identifier: The identifier used to request from the cache.
Context: The context which differentiates between cache results.
Failure: The possible failures when requesting the cache.
Value: The possible successful value when requesting the cache.

Functions¶

cachedInMemory¶

fun <Identifier, Context, Failure, Value> ContextualCache<Identifier, Context, Failure, Value>.cachedInMemory(job: Job): ContextualCache<Identifier, Context, Failure, Value>

In-memory ContextualCache layer.

See also

cachedInMemory: Non-contextual equivalent

expire¶

open suspend fun expire(id: Identifier)

Tells the cache that the values it stores for the given id are out of date, no matter the context, and should be queried again the next time they are requested.

All layers are updated.

open suspend fun expire(id: Identifier, context: Context)

Tells the cache that the value it stores for the given id and context is out of date, and should be queried again the next time they are requested.

All layers are updated.

abstract suspend fun expire(ids: Collection<Identifier>)

Tells the cache that the values it stores for the given ids are out of date, no matter the context, and should be queried again the next time they are requested.

All layers are updated.

expireAfter¶

fun <Identifier, Context, Failure, Value> ContextualCache<Identifier, Context, Failure, Value>.expireAfter(
    duration: Duration, 
    scope: CoroutineScope, 
    clock: Clock
): ContextualCache<Identifier, Context, Failure, Value>

Age-based ContextualCache expiration strategy.

See also

expireAfter: Non-contextual equivalent

expireAll¶

abstract suspend fun expireAll()

Tells the cache that all values are out of date, and should be queried again the next time they are requested.

All layers are updated.

expireContextual¶

abstract suspend fun expireContextual(ids: Collection<Pair<Identifier, Context>>)

Tells the cache that the values it stores for the given ids are out of date, and should be queried again the next time they are requested.

All layers are updated.

get¶

abstract operator fun get(id: Identifier, context: Context): ProgressiveFlow<Failure, Value>

Gets the value associated with an id and a context in this cache.

This function returns a Flow instance synchronously: it is safe to call in synchronous-only areas of the program, such as inside the body of a UI component. You can then subscribe to the Flow to access the actual values.

update¶

open suspend fun update(
    id: Identifier, 
    context: Context, 
    value: Value
)

Forces the cache to accept value as a more recent value for the given id and context than whatever it was previously storing.

All layers are updated.

abstract suspend fun update(values: Collection<Triple<Identifier, Context, Value>>)

Forces the cache to accept the given values as more recent for their associated identifier than whatever was previously stored.

All layers are updated.