commons-provider/xyz.xenondevs.commons.provider/Provider

Provider

sealed interface Provider<out T> : Supplier<T>

A Provider is a thread-safe, lazily-evaluated, reactive data source that holds a single value of type T.

Using map, flatMap, and various extension functions, atomic data transformations can be modelled.

Additionally, it is also possible to subscribe to and observe providers. Note that subscribing disables the lazy evaluation of the provider, as the value will need to be calculated immediately when an update happens in order to propagate it to the subscribers.

It is important that all data transformation functions are pure, meaning that they are side effect free and do not access any mutable external state, in order to maintain the integrity of lazy evaluation. It is especially important that they do not resolve any other provider's value, as doing so may risk deadlocks. To properly operate on the values of multiple providers, combine them first via combinedProvider.

Usage example:

val provider0 = provider { "Hello" } // Provider with lazy value of "Hello"
val provider1 = provider0.map { it + ", World!" } // Lazily maps the value of provider by appending ", World!" to it

println(provider1.get()) // "Hello, World!" (runs lambdas above)
println(provider1.get()) // "Hello, World!" (cached value)

Inheritors

MutableProvider

Properties

children

abstract val children: Set<Provider<*>>

A snapshot of the direct children of this Provider. May not necessarily contain children if it can be determined that no updates will be sent to them.

parents

abstract val parents: Set<Provider<*>>

A snapshot of the direct parents of this Provider. May not necessarily contain parents if it can be determined that no updates will be received from them.

Functions

flatMap

abstract fun <R> flatMap(transform: (T) -> Provider<R>): Provider<R>

Creates and returns a new Provider that maps to the value of the Provider returned by transform.

flatMapCollection

inline fun <T, R> Provider<Collection<T>>.flatMapCollection(crossinline transform: (T) -> Iterable<R>): Provider<List<R>>

Creates and returns a new Provider that flat-maps the elements of the Collection obtained from this into a list using the transform function.

flatMapCollectionTo

inline fun <T, R, C : MutableCollection<in R>> Provider<Collection<T>>.flatMapCollectionTo(crossinline makeCollection: (size: Int) -> C, crossinline transform: (T) -> Iterable<R>): Provider<C>

Creates and returns a new Provider that flat-maps the elements of the Collection obtained from this into a collection created by makeCollection using the transform function.

flatMapMutable

abstract fun <R> flatMapMutable(transform: (T) -> MutableProvider<R>): MutableProvider<R>

Creates and returns a new MutableProvider that maps to the value of the MutableProvider returned by transform.

flatten

fun <R> Provider<MutableProvider<R>>.flatten(): MutableProvider<R>

fun <R> Provider<Provider<R>>.flatten(): Provider<R>

Creates and returns a new Provider that maps to the provider that is the value of this.

flattenIterables

fun <T> Provider<Iterable<Iterable<T>>>.flattenIterables(): Provider<List<T>>

Creates and returns a new Provider that flattens the List of Lists obtained from this.

get

abstract fun get(): @UnsafeVariance T

get

@JvmName(name = "arrayGet")

operator fun <T> Provider<Array<T>>.get(index: Int): Provider<T>

@JvmName(name = "arrayGet")

operator fun <T> Provider<Array<T>>.get(index: Provider<Int>): Provider<T>

@JvmName(name = "listGet")

operator fun <T> Provider<List<T>>.get(index: Int): Provider<T>

@JvmName(name = "listGet")

operator fun <T> Provider<List<T>>.get(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index or throws NoSuchElementException.

getCoerced

@JvmName(name = "arrayGetCoerced")

fun <T> Provider<Array<T>>.getCoerced(index: Int): Provider<T>

@JvmName(name = "arrayGetCoerced")

fun <T> Provider<Array<T>>.getCoerced(index: Provider<Int>): Provider<T>

@JvmName(name = "listGetCoerced")

fun <T> Provider<List<T>>.getCoerced(index: Int): Provider<T>

@JvmName(name = "listGetCoerced")

fun <T> Provider<List<T>>.getCoerced(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index or the element at the closest valid index.

getMod

@JvmName(name = "arrayGetMod")

fun <T> Provider<Array<T>>.getMod(index: Int): Provider<T>

@JvmName(name = "arrayGetMod")

fun <T> Provider<Array<T>>.getMod(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index modulo the array size.

@JvmName(name = "listGetMod")

fun <T> Provider<List<T>>.getMod(index: Int): Provider<T>

@JvmName(name = "listGetMod")

fun <T> Provider<List<T>>.getMod(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index modulo the list size.

getOrNull

@JvmName(name = "arrayGetOrNull")

fun <T> Provider<Array<T>>.getOrNull(index: Int): Provider<T?>

@JvmName(name = "arrayGetOrNull")

fun <T> Provider<Array<T>>.getOrNull(index: Provider<Int>): Provider<T?>

@JvmName(name = "listGetOrNull")

fun <T> Provider<List<T>>.getOrNull(index: Int): Provider<T?>

@JvmName(name = "listGetOrNull")

fun <T> Provider<List<T>>.getOrNull(index: Provider<Int>): Provider<T?>

Creates and returns a new Provider that maps to the element at index or null if the index is out of bounds.

getValue

open operator fun <X> getValue(thisRef: X?, property: KProperty<*>?): T

lazyFlatMap

abstract fun <R> lazyFlatMap(transform: (T) -> Provider<R>): Provider<R>

Creates and returns new Provider that lazily maps to the value of the Provider returned by transform.

lazyFlatMapMutable

abstract fun <R> lazyFlatMapMutable(transform: (T) -> MutableProvider<R>): MutableProvider<R>

Creates and returns new MutableProvider that lazily maps to the value of the MutableProvider returned by transform.

lazyFlatten

fun <R> Provider<MutableProvider<R>>.lazyFlatten(): MutableProvider<R>

fun <R> Provider<Provider<R>>.lazyFlatten(): Provider<R>

Creates and returns a new Provider that lazily maps to the provider that is the value of this.

map

abstract fun <R> map(transform: (T) -> R): Provider<R>

Creates and returns a new Provider that maps the value of this using the transform function.

mapEach

inline fun <T, R> Provider<Collection<T>>.mapEach(crossinline transform: (T) -> R): Provider<List<R>>

Creates and returns a new Provider that maps each element of the Collection obtained from this using the transform function.

mapEachNotNull

inline fun <T, R : Any> Provider<Collection<T>>.mapEachNotNull(crossinline transform: (T) -> R?): Provider<List<R>>

Creates and returns a new Provider that maps each element of the Collection obtained from this using the transform function and filters out all null results.

mapEachNotNullTo

inline fun <T, R : Any, C : MutableCollection<in R>> Provider<Collection<T>>.mapEachNotNullTo(crossinline makeCollection: (size: Int) -> C, crossinline transform: (T) -> R?): Provider<C>

Creates and returns a new Provider that maps each element of the Collection obtained from this using the transform function and filters out all null results. The results are added to a collection created by makeCollection.

mapEachTo

inline fun <T, R, C : MutableCollection<in R>> Provider<Collection<T>>.mapEachTo(crossinline makeCollection: (size: Int) -> C, crossinline transform: (T) -> R): Provider<C>

Creates and returns a new Provider that maps each element of the Collection obtained from this using the transform function and adds the results to a collection created by makeCollection.

mapNonNull

inline fun <T : Any, R> Provider<T?>.mapNonNull(crossinline transform: (T) -> R): Provider<R?>

Creates and returns a new Provider that maps non-null values of this using the transform function. Null values will be passed through without transformation.

mergeMaps

fun <K, V> Provider<List<Map<K, V>>>.mergeMaps(): Provider<Map<K, V>>

Creates and returns a new Provider that merges all Maps obtained from this into a single Map.

mergeMapsTo

fun <K, V, M : MutableMap<in K, in V>> Provider<List<Map<K, V>>>.mergeMapsTo(makeMap: (size: Int) -> M): Provider<M>

Creates and returns a new Provider that merges all Maps obtained from this into a single Map, which is created by the makeMap function.

observe

abstract fun observe(action: () -> Unit)

Registers a function that will be called whenever the value of this Provider changes. If multiple threads update the value concurrently, intermediate observer invocations may be skipped.

observeWeak

abstract fun <R : Any> observeWeak(owner: R, action: (owner: R) -> Unit)

Registers a weak observer that will be called when the value of this Provider changes. If multiple threads update the value concurrently, intermediate observer invocations may be skipped. The observer will be automatically removed when the owner is garbage collected.

orElse

fun <T> Provider<T?>.orElse(value: T): Provider<T>

Creates and returns a new Provider that returns a fallback value if the value of this is null.

fun <T> Provider<T?>.orElse(provider: Provider<T>): Provider<T>

Creates and returns a new Provider that returns a fallback value obtained through provider if the value of this is null.

@JvmName(name = "orElseNullable")

fun <T> Provider<T?>.orElse(provider: Provider<T>?): Provider<T?>

If provider is null, returns this. If provider is not null, creates and returns a new Provider that returns a fallback value obtained through provider if the value of this is null.

orElseLazily

fun <T> Provider<T?>.orElseLazily(lazyValue: () -> T): Provider<T>

Creates and returns a new Provider that returns a fallback value obtained through provider if the value of this is null.

orElseNew

fun <T> Provider<T?>.orElseNew(newValue: () -> T): Provider<T>

Creates a new Provider that returns a fallback value which is re-created through the newValue lambda every time the value of this is set to null.

require

inline fun <T> Provider<T>.require(crossinline condition: (T) -> Boolean, crossinline message: (T) -> String): Provider<T>

Creates and returns a new Provider that throws an IllegalArgumentException with a message generated by message if condition fails.

requireNotNull

inline fun <T : Any> Provider<T?>.requireNotNull(crossinline message: () -> String): Provider<T>

Creates and returns a new Provider that throws an IllegalArgumentException with a message generated by message if the value is null.

fun <T : Any> Provider<T?>.requireNotNull(message: String = "Required value was null."): Provider<T>

Creates and returns a new Provider that throws an IllegalArgumentException with message if the value is null.

strongFlatMap

abstract fun <R> strongFlatMap(transform: (T) -> Provider<R>): Provider<R>

Creates and returns a new Provider that maps to the value of the Provider returned by transform.

strongFlatMapCollection

inline fun <T, R> Provider<Collection<T>>.strongFlatMapCollection(crossinline transform: (T) -> Iterable<R>): Provider<List<R>>

Creates and returns a new Provider that flat-maps the elements of the Collection obtained from this into a list using the transform function.

strongFlatMapCollectionTo

inline fun <T, R, C : MutableCollection<in R>> Provider<Collection<T>>.strongFlatMapCollectionTo(crossinline makeCollection: (size: Int) -> C, crossinline transform: (T) -> Iterable<R>): Provider<C>

Creates and returns a new Provider that flat-maps the elements of the Collection obtained from this into a collection created by makeCollection using the transform function.

strongFlatMapMutable

abstract fun <R> strongFlatMapMutable(transform: (T) -> MutableProvider<R>): MutableProvider<R>

Creates and returns a new MutableProvider that maps to the value of the MutableProvider returned by transform.

strongFlatten

fun <R> Provider<MutableProvider<R>>.strongFlatten(): MutableProvider<R>

fun <R> Provider<Provider<R>>.strongFlatten(): Provider<R>

Creates and returns a new Provider that maps to the provider that is the value of this.

strongFlattenIterables

fun <T> Provider<Iterable<Iterable<T>>>.strongFlattenIterables(): Provider<List<T>>

Creates and returns a new Provider that flattens the List of Lists obtained from this.

strongGet

@JvmName(name = "strongArrayGet")

fun <T> Provider<Array<T>>.strongGet(index: Int): Provider<T>

@JvmName(name = "strongArrayGet")

fun <T> Provider<Array<T>>.strongGet(index: Provider<Int>): Provider<T>

@JvmName(name = "strongListGet")

fun <T> Provider<List<T>>.strongGet(index: Int): Provider<T>

@JvmName(name = "strongListGet")

fun <T> Provider<List<T>>.strongGet(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index or throws NoSuchElementException.

strongGetCoerced

@JvmName(name = "strongArrayGetCoerced")

fun <T> Provider<Array<T>>.strongGetCoerced(index: Int): Provider<T>

@JvmName(name = "strongArrayGetCoerced")

fun <T> Provider<Array<T>>.strongGetCoerced(index: Provider<Int>): Provider<T>

@JvmName(name = "strongListGetCoerced")

fun <T> Provider<List<T>>.strongGetCoerced(index: Int): Provider<T>

@JvmName(name = "strongListGetCoerced")

fun <T> Provider<List<T>>.strongGetCoerced(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index or the element at the closest valid index.

strongGetMod

@JvmName(name = "strongArrayGetMod")

fun <T> Provider<Array<T>>.strongGetMod(index: Int): Provider<T>

@JvmName(name = "strongArrayGetMod")

fun <T> Provider<Array<T>>.strongGetMod(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index modulo the array size.

@JvmName(name = "strongListGetMod")

fun <T> Provider<List<T>>.strongGetMod(index: Int): Provider<T>

@JvmName(name = "strongListGetMod")

fun <T> Provider<List<T>>.strongGetMod(index: Provider<Int>): Provider<T>

Creates and returns a new Provider that maps to the element at index modulo the list size.

strongGetOrNull

@JvmName(name = "strongArrayGetOrNull")

fun <T> Provider<Array<T>>.strongGetOrNull(index: Int): Provider<T?>

@JvmName(name = "strongArrayGetOrNull")

fun <T> Provider<Array<T>>.strongGetOrNull(index: Provider<Int>): Provider<T?>

@JvmName(name = "strongListGetOrNull")

fun <T> Provider<List<T>>.strongGetOrNull(index: Int): Provider<T?>

@JvmName(name = "strongListGetOrNull")

fun <T> Provider<List<T>>.strongGetOrNull(index: Provider<Int>): Provider<T?>

Creates and returns a new Provider that maps to the element at index or null if the index is out of bounds.

strongLazyFlatMap

abstract fun <R> strongLazyFlatMap(transform: (T) -> Provider<R>): Provider<R>

Creates and returns new Provider that lazily maps to the value of the Provider returned by transform.

strongLazyFlatMapMutable

abstract fun <R> strongLazyFlatMapMutable(transform: (T) -> MutableProvider<R>): MutableProvider<R>

Creates and returns new MutableProvider that lazily maps to the value of the MutableProvider returned by transform.

strongLazyFlatten

fun <R> Provider<MutableProvider<R>>.strongLazyFlatten(): MutableProvider<R>

fun <R> Provider<Provider<R>>.strongLazyFlatten(): Provider<R>

Creates and returns a new Provider that lazily maps to the provider that is the value of this.

strongMap

abstract fun <R> strongMap(transform: (T) -> R): Provider<R>

Creates and returns a new Provider that maps the value of this using the transform function.

strongMapEach

inline fun <T, R> Provider<Collection<T>>.strongMapEach(crossinline transform: (T) -> R): Provider<List<R>>

Creates and returns a new Provider that maps each element of the Collection obtained from this using the transform function.

strongMapEachNotNull

inline fun <T, R : Any> Provider<Collection<T>>.strongMapEachNotNull(crossinline transform: (T) -> R?): Provider<List<R>>

Creates and returns a new Provider that maps each element of the Collection obtained from this using the transform function and filters out all null results.

strongMapEachNotNullTo

inline fun <T, R : Any, C : MutableCollection<in R>> Provider<Collection<T>>.strongMapEachNotNullTo(crossinline makeCollection: (size: Int) -> C, crossinline transform: (T) -> R?): Provider<C>

strongMapEachTo

inline fun <T, R, C : MutableCollection<in R>> Provider<Collection<T>>.strongMapEachTo(crossinline makeCollection: (size: Int) -> C, crossinline transform: (T) -> R): Provider<C>

Creates and returns a new Provider that maps each element of the Collection obtained from this using the transform function and adds the results to a collection created by makeCollection.

strongMapNonNull

inline fun <T : Any, R> Provider<T?>.strongMapNonNull(crossinline transform: (T) -> R): Provider<R?>

Creates and returns a new Provider that maps non-null values of this using the transform function. Null values will be passed through without transformation.

strongMergeMaps

fun <K, V> Provider<List<Map<K, V>>>.strongMergeMaps(): Provider<Map<K, V>>

Creates and returns a new Provider that merges all Maps obtained from this into a single Map.

strongMergeMapsTo

fun <K, V, M : MutableMap<in K, in V>> Provider<List<Map<K, V>>>.strongMergeMapsTo(makeMap: (size: Int) -> M): Provider<M>

Creates and returns a new Provider that merges all Maps obtained from this into a single Map, which is created by the makeMap function.

strongOrElse

fun <T> Provider<T?>.strongOrElse(value: T): Provider<T>

Creates and returns a new Provider that returns a fallback value if the value of this is null.

fun <T> Provider<T?>.strongOrElse(provider: Provider<T>): Provider<T>

Creates and returns a new Provider that returns a fallback value obtained through provider if the value of this is null.

@JvmName(name = "strongOrElseNullable")

fun <T> Provider<T?>.strongOrElse(provider: Provider<T>?): Provider<T?>

If provider is null, returns this. If provider is not null, creates and returns a new Provider that returns a fallback value obtained through provider if the value of this is null.

strongOrElseLazily

fun <T> Provider<T?>.strongOrElseLazily(lazyValue: () -> T): Provider<T>

Creates and returns a new Provider that returns a fallback value obtained through provider if the value of this is null.

strongOrElseNew

fun <T> Provider<T?>.strongOrElseNew(newValue: () -> T): Provider<T>

Creates a new Provider that returns a fallback value which is re-created through the newValue lambda every time the value of this is set to null.

strongRequire

inline fun <T> Provider<T>.strongRequire(crossinline condition: (T) -> Boolean, crossinline message: (T) -> String): Provider<T>

Creates and returns a new Provider that throws an IllegalArgumentException with a message generated by message if condition fails.

strongRequireNotNull

inline fun <T : Any> Provider<T?>.strongRequireNotNull(crossinline message: () -> String): Provider<T>

Creates and returns a new Provider that throws an IllegalArgumentException with a message generated by message if the value is null.

fun <T : Any> Provider<T?>.strongRequireNotNull(message: String = "Required value was null."): Provider<T>

Creates and returns a new Provider that throws an IllegalArgumentException with message if the value is null.

abstract fun subscribe(action: (value: T) -> Unit)

Registers a function that will be called with the new value whenever the value of this Provider changes. If multiple threads update the value concurrently, intermediate subscriber invocations may be skipped, but the supplied value will always be the most recent one.

subscribeWeak

abstract fun <R : Any> subscribeWeak(owner: R, action: (owner: R, value: T) -> Unit)

Registers a weak subscriber that will be called when the value of this Provider changes. If multiple threads update the value concurrently, subscriber invocations may be skipped, but the supplied value will always be the most recent one. The subscriber will be automatically removed when the owner is garbage collected.

unobserve